跨项目共享自定义元素(custom elements)实现方案咨询

CRA默认输出的预构建全站bundle本身就不是为嵌入其他项目设计的：它的默认逻辑是加载完成后直接查找页面上id为root的全局DOM节点挂载React应用，既没有自定义元素注册逻辑，也没做挂载目标适配、作用域隔离、依赖冲突处理，直接引入后无法渲染是正常结果。以下是可落地的生产级实现方案：

方案1：原生封装+调整Project1打包为库模式 #

这是稳定性最高、额外依赖最少的方案。

• 第一步：在Project1中新增Web Component专属入口文件，将整个应用/单个组件封装为标准自定义元素，核心逻辑是在自定义元素的生命周期钩子内完成React根的挂载、更新、卸载，参考代码：

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import './index.css';

class Project1App extends HTMLElement {
  constructor() {
    super();
    // 开启shadow DOM做样式隔离，避免两个项目样式互相污染
    this.shadow = this.attachShadow({ mode: 'open' });
    this.mountNode = document.createElement('div');
    this.shadow.appendChild(this.mountNode);
  }

  connectedCallback() {
    this.reactRoot = createRoot(this.mountNode);
    this.renderReactApp();
  }

  disconnectedCallback() {
    this.reactRoot?.unmount();
  }

  // 声明需要从外层透传给React的属性
  static get observedAttributes() {
    return ['user-id', 'theme'];
  }

  attributeChangedCallback() {
    this.renderReactApp();
  }

  renderReactApp() {
    if (!this.reactRoot) return;
    // 收集自定义元素上的属性作为React组件props
    const props = Array.from(this.attributes).reduce((acc, attr) => {
      acc[attr.name] = attr.value;
      return acc;
    }, {});
    this.reactRoot.render(<App {...props} />);
  }
}

// 避免重复注册元素抛错
if (!customElements.get('project1-app')) {
  customElements.define('project1-app', Project1App);
}

注意：如果Project1使用了react-router，必须将原有BrowserRouter/HashRouter替换为MemoryRouter，否则路由状态会和Project2的全局URL路由互相干扰。跨项目通信可以在自定义元素内部通过dispatchEvent抛出标准自定义事件，外层Project2直接用addEventListener监听即可。

• 第二步：修改CRA打包配置，无需eject即可用craco或react-app-rewired覆盖默认配置，将打包目标改为库模式，入口指向上述自定义元素文件，关闭runtimeChunk、splitChunks避免多文件依赖问题，输出单文件UMD/ESM格式bundle，打包时建议把react、react-dom打入bundle闭包，避免和外部环境的依赖产生冲突。
• 第三步：Project2中直接用script标签引入打包好的单文件bundle，就可以直接在页面中使用<project1-app user-id="xxx" theme="dark"></project1-app>标签渲染，不需要额外逻辑。

方案2：借助成熟封装库减少重复逻辑 #

如果需要封装的组件数量多，不想重复编写属性监听、事件透传、样式注入、内存清理逻辑，可以直接用成熟的React转Web Component工具类库，这类库会自动处理：

• shadow DOM内部的样式注入，解决CSS Module、全局样式在shadow DOM内不生效的问题
• React事件到原生DOM事件的转换，外层可以直接用原生DOM方法监听组件内部抛出的事件
• 属性类型自动转换，避免数字、布尔值被默认序列化为字符串的问题
• 组件卸载时的React根销毁、事件解绑，规避内存泄漏风险
  打包逻辑和方案1一致，走库模式输出单文件bundle即可，开发效率远高于手写原生封装。

方案3：平滑过渡适配方案 #

如果短期没有精力完成全量React组件的Web Component改造，可以先做一层适配层降低迁移成本：

• 编写一个自定义元素，内部暂时沿用原有iframe逻辑加载Project1页面
• 在自定义元素内部封装iframe的高度自适应、跨域postMessage通信逻辑，对外暴露的属性、方法、事件API和后续纯React实现的Web Component保持完全一致
• Project2侧直接调用这个自定义元素，等后续完成纯React版本的封装后，只需要替换自定义元素的内部实现，上层Project2的业务代码不需要做任何修改，实现无感知平滑迁移。

预构建bundle渲染失败的高频排查点 #

如果仍想复用现有预构建bundle，优先排查这几个问题：

1. 检查自定义元素注册时机：引入bundle的script标签要加defer属性，或者放在页面底部，避免标签解析到自定义元素时JS还未执行完注册逻辑，导致元素被识别为未知元素无法正常升级渲染
2. 检查依赖冲突：如果bundle没有把react、react-dom做闭包内联，而是暴露到全局，很容易和页面上其他版本的React产生冲突导致挂载失败
3. 检查挂载目标：CRA默认bundle是挂载到document.getElementById('root')全局节点上的，如果没有改写挂载逻辑，自然不会渲染到自定义元素内部
4. 检查样式生效逻辑：如果开启了shadow DOM，默认打包出来的样式是注入到全局document.head的，shadow DOM内部的元素无法继承这些样式，会出现DOM结构渲染完成但样式完全错乱的问题

内容的提问来源于stack exchange，提问作者Zlatan Sadibasic