如何在Next.js应用中开发无需iframe即可嵌入任意站点的Widget
Next.js 无iframe嵌入式Widget实现方案
核心实现逻辑
不依赖iframe的嵌入式Widget本质是将你的React组件单独打包成可独立执行的UMD/ES模块包,第三方站点仅需引入一段JS脚本、指定挂载容器即可完成嵌入,无跨域限制、适配性更强。
具体实现步骤
- 抽离独立Widget组件
首先将需要封装的组件从Next.js业务逻辑中抽离为独立单元,禁止依赖Next.js专属API,包括next/router、next/image、服务端组件能力等,如果必须用到路由/图片能力,要替换为原生浏览器API或者通用兼容方案;如果是App Router项目,组件顶部必须加'use client'声明为客户端组件。 - 配置独立打包规则
不要用Next.js自带的打包能力,选择Vite/Rollup单独打包Widget,输出UMD格式兼容所有站点环境,以下是Vite配置示例:
在// vite.widget.config.js import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], build: { lib: { entry: 'src/components/TargetWidget/index.jsx', name: 'MySiteWidget', // 全局暴露的变量名,第三方站点直接调用 fileName: (format) => `my-widget.${format}.js`, formats: ['umd'] }, rollupOptions: { // 若要减小包体积可外置react/react-dom,第三方站点需提前引入这两个依赖 // external: ['react', 'react-dom'], output: { globals: { react: 'React', 'react-dom': 'ReactDOM' } } } } })package.json中新增打包命令:"scripts": { "build:widget": "vite build --config vite.widget.config.js" } - 编写对外暴露的接入方法
在Widget入口文件中暴露初始化方法,同时支持手动调用和自动挂载:// src/components/TargetWidget/index.jsx import React from 'react' import ReactDOM from 'react-dom/client' import TargetWidget from './TargetWidget' // 暴露给第三方站点的渲染方法 export function render(containerSelector, customProps = {}) { const container = document.querySelector(containerSelector) if (!container) return console.error('Widget挂载容器不存在') const root = ReactDOM.createRoot(container) root.render(<TargetWidget {...customProps} />) } // 支持自动挂载,第三方站点加对应属性即可无需手动调用初始化 if (document.querySelector('[data-my-widget-auto-mount]')) { render('[data-my-widget-auto-mount]') } - 处理样式隔离
无iframe嵌入最容易出现样式冲突,推荐两种解决方案:- 用CSS-in-JS方案(styled-components/emotion)生成唯一哈希类名,全局不会和第三方站点样式冲突
- 用Shadow DOM做完全隔离,修改render方法即可:
export function render(containerSelector, customProps = {}) { const container = document.querySelector(containerSelector) if (!container) return console.error('Widget挂载容器不存在') // 开启Shadow DOM隔离 const shadowRoot = container.attachShadow({ mode: 'open' }) const root = ReactDOM.createRoot(shadowRoot) // 手动注入Widget样式 const styleEl = document.createElement('style') styleEl.textContent = `/* 这里放你Widget的所有样式代码 */` shadowRoot.appendChild(styleEl) root.render(<TargetWidget {...customProps} />) } - 部署与发布
执行npm run build:widget打包后,将产物放到Next.js项目的public/widget目录下,Next.js会自动托管该静态资源,第三方站点仅需如下代码即可完成嵌入:<!-- 挂载容器 --> <div id="my-widget-container"></div> <!-- 引入Widget脚本,地址替换为你站点的实际地址 --> <script src="https://你的站点域名/widget/my-widget.umd.js"></script> <!-- 初始化Widget --> <script> MySiteWidget.render('#my-widget-container', { // 支持传入自定义参数,比如主题、配置项等 theme: 'light', showHeader: false }) </script>
注意事项
- 所有涉及跨域的接口请求,你的Next.js站点需要配置CORS规则,允许第三方站点域名访问
- 尽量压缩包体积,非必要依赖不要打包进去,如果把react/react-dom全量打包,最终产物控制在100KB以内不会影响第三方站点加载速度
- 所有用到的浏览器API要做兼容判断,避免在低版本浏览器或者特殊站点环境下报错
内容的提问来源于stack exchange,提问作者Ali khan
相关产品推荐
相关产品推荐

