如何导出NextJS项目为模块供Ruby on Rails仪表盘嵌入预览

该方案全程不需要在Rails项目中配置npm/node环境，所有构建动作都在原有Next.js仓库内完成，Rails侧仅需加载构建完成的静态文件即可，同时支持实时传参修改组件属性，满足预览需求。

Next.js侧改造（全部在原有Next仓库完成，不涉及Rails环境改动） #

• 新增独立嵌入入口文件，不要复用Next.js原有服务端/路由运行时入口，新建src/embed-entry.jsx，引入顶层业务组件，将渲染方法挂载到全局window对象：

// src/embed-entry.jsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import TopAppComponent from './pages/index'; // 原有项目的顶层入口组件

window.renderNextPreview = (containerDom, componentProps = {}) => {
  const root = createRoot(containerDom);
  root.render(<TopAppComponent {...componentProps} />);
  // 返回卸载方法，避免内存泄漏
  return () => root.unmount();
};

• 新增独立构建配置（不要修改原有Next.js构建逻辑，两套构建流程完全隔离），可以用webpack或者vite，输出UMD格式的静态资源，将react、react-dom直接打包进产物，消除外部依赖。最终产出next-preview.js和next-preview.css两个文件，直接放到Rails项目可访问的静态资源目录即可（比如Rails的public目录、内部静态资源CDN，整个过程只需要拷贝文件，不需要在Rails侧执行任何npm命令）。

之前webpack打包出现页面冻结，基本是两个原因：一是重复打包React运行时导致冲突，二是没有正确处理挂载/卸载逻辑触发循环渲染，按照上面独立入口+把react/react-dom纳入打包依赖的方式配置即可解决。

Rails侧实现（零npm依赖） #

• 在仪表盘的手机外观容器内预留渲染节点：

<div class="phone-shell">
  <div id="next-preview-mount"></div>
</div>

• 页面内直接引入构建好的静态资源，和引入普通前端插件没有区别：

<link rel="stylesheet" href="/public-assets/next-preview.css">
<script src="/public-assets/next-preview.js"></script>

• 需要修改组件属性（比如文字颜色）时，直接调用全局挂载的渲染方法传参即可，无跨域限制，实时生效：

// 示例：监听仪表盘颜色选择器的修改事件
colorPickerInput.addEventListener('change', (e) => {
  const mountNode = document.getElementById('next-preview-mount');
  window.renderNextPreview(mountNode, {
    textColor: e.target.value
  });
});

方案适配性说明 #

• 完全满足Rails侧不配置npm环境的核心要求：Rails侧不需要任何node相关构建、依赖安装动作，仅加载普通静态资源
• 相比iframe方案无跨域通信成本：传参、事件绑定都是原生JS方法调用，没有延迟，不需要处理postMessage逻辑
• 不需要拆分原有Next.js项目：所有改造都在原有仓库内完成，业务代码不需要迁移到独立公共库，只是多了一个嵌入版本的构建流程
• 避免直接引入源码的编译问题：所有JSX、样式编译动作都在Next侧提前完成，Rails侧不需要做任何语法兼容处理

避坑点 #

• 构建时将组件用到的图片、字体等静态资源路径改为绝对路径，避免Rails页面加载时出现404
• 如果项目用到了next/router、next/image这类Next专属API，在嵌入入口做简单mock即可——预览场景不需要完整的Next路由、服务端图片优化能力，比如router可以传空对象占位，next/image替换为原生img标签
• 后续Next侧业务代码更新后，只需要重新执行嵌入包构建命令，替换Rails侧的两个静态文件即可，不需要改动Rails业务代码

内容的提问来源于stack exchange，提问作者Thales Kenne