本文介绍如何将基于 react 和 next.js 构建的活动页面打包成轻量、跨域、无依赖的可嵌入 html 小工具，使活动主办方能通过一行 script 标签将其部署到任意第三方网站。
本文介绍如何将基于 react 和 next.js 构建的活动页面打包成轻量、跨域、无依赖的可嵌入 html 小工具，使活动主办方能通过一行 script 标签将其部署到任意第三方网站。
要将你的 React/Next.js 活动项目转化为可嵌入的网页小工具（Embeddable Widget），核心思路是：脱离服务端渲染与路由体系，构建一个独立、自包含、沙箱化运行的客户端组件，并通过 <script> 标签注入目标页面。这并非直接部署 Next.js 应用，而是将其“降级”为纯前端微前端模块。
✅ 正确做法：构建独立 Widget 包
-
创建专用 Widget 入口文件（如 widget/index.tsx）：
// widget/index.tsx import React from 'react'; import { createRoot } from 'react-dom/client'; import EventWidget from '../components/EventWidget'; // 你的活动展示组件
// 接收外部参数（如 eventID、theme、lang） const init = (options: { containerId: string; eventID: string; theme?: 'light' | 'dark' }) => { const container = document.getElementById(options.containerId); if (!container) return;
const root = createRoot(container); root.render(
// 挂载到全局，供外部调用 (window as any).__EVENT_WIDGET__ = { init };
2. **配置独立构建脚本**（不依赖 Next.js Server Components 或 App Router）
使用 Vite 或 Webpack 打包为 UMD/IIFE 格式，输出单个 JS 文件（如 `event-widget.js`），并确保：
- 启用 `external: ['react', 'react-dom']`（避免重复引入 React）；
- 或内联 React（仅当目标页无 React 时）——推荐使用 [`@vitejs/plugin-react-swc`](https://github.com/vitejs/vite-plugin-react-swc) + `build.lib` 模式。
3. **生成嵌入代码模板**（提供给活动主办方）：
```html
<!-- 任意第三方网站中插入 -->
<div id="my-event-widget"></div>
<script src="https://cdn.yourdomain.com/event-widget.js" async></script>
<script>
__EVENT_WIDGET__.init({
containerId: 'my-event-widget',
eventID: 'evt_abc123',
theme: 'light'
});
</script>⚠️ 注意事项
- 避免 SSR 依赖：禁用 getServerSideProps、useRouter、next/image 等 Next.js 特有 API；改用 fetch() + 客户端状态管理。
- 样式隔离：使用 CSS Modules、CSS-in-JS（如 Emotion）或 :where()/data-* 属性前缀防止样式污染。
- 跨域安全：后端 API 需支持 CORS，且 Widget 请求应携带 credentials: 'same-origin' 或明确配置。
- 性能优化：启用代码分割（import() 动态加载）、预加载关键资源、添加 crossorigin="anonymous" 防止错误丢失堆栈。
✅ 最终效果
主办方只需复制粘贴一段 HTML，即可在 WordPress、Wix、静态官网等任意页面中呈现你的活动内容——完全解耦、零构建依赖、支持多实例共存。
这种模式已在生产环境广泛验证（如 Calendly、Typeform、Tally 表单嵌入），是你作为活动技术平台交付标准化、可扩展集成能力的关键一步。
