You need to enable JavaScript to run this app. 如何在Next.js应用中开发无需iframe即可嵌入任意站点的Widget
优惠活动
大模型
产品
解决方案
定价
更多

如何在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嵌入最容易出现样式冲突,推荐两种解决方案:
    1. 用CSS-in-JS方案(styled-components/emotion)生成唯一哈希类名,全局不会和第三方站点样式冲突
    2. 用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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.13 20:24:02