企业官网建设流程全解析

Argo CD UI 扩展 React 19 升级指南：externals 配置与react/jsx-runtime修复方案

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd

自 Argo CD 3.5 起，宿主 UI 已从 React 16 升级到 React 19。本文围绕 docs/operator-manual/upgrading/ui-extensions-react-19-upgrading.md 这一官方升级文档展开，完整讲解 UI 扩展在加载时报TypeError的根因、识别方法、通过 webpackexternals外部化react/jsx-runtime的修复步骤，以及宿主 UI 为扩展暴露的全局模块清单，帮助扩展维护者在升级到 Argo CD 3.5+ 后快速完成适配并回归可用状态。

背景：Argo CD 3.5 将宿主 UI 升级到 React 19

Argo CD 的 Web 界面支持通过 UI 扩展机制挂载自定义 React 组件（资源标签页、系统级页面、应用视图、状态面板、顶栏操作菜单等）。扩展以独立的 JavaScript 文件交付，放置在argocd-serverPod 的/tmp/extensions目录中，文件名需匹配^extension(.*)\.js$，并在页面初始渲染时通过全局extensionsAPI注册自身（参见 docs/developer-guide/extensions/ui-extensions.md）。

在升级到 Argo CD 3.5 之前，宿主 UI 运行在 React 16 之上。3.5 版本将宿主 UI 升级到 React 19，这给所有基于旧版本构建的 UI 扩展带来一个兼容性门槛：扩展必须额外外部化react/jsx-runtime。宿主应用会将该 JSX 运行时暴露为window.ReactJSXRuntime；扩展如果仍然在自己的 bundle 中内置一份运行时副本，将无法正常加载。

官方升级文档在 docs/operator-manual/upgrading/3.4-3.5.md 中同步记录了这条变更："UI extensions built against an older Argo CD UI may fail to load with aTypeErroruntil they are rebuilt to externalizereact/jsx-runtime."（未安装 UI 扩展的用户无需任何操作。）

故障现象：扩展加载时的TypeError

针对旧版 Argo CD UI 构建的扩展，升级到 3.5+ 后会在加载阶段直接失败，宿主 UI 会以如下形式报错：

Extension <name>.js failed to load: TypeError: Cannot read properties of undefined (reading '<prop>')

需要特别注意的是，报错信息中的属性名（<prop>）以及堆栈中的函数名不可作为可靠匹配依据——它们会随扩展 bundle 是否被压缩（minified）而变化。真正在所有构建形态下都成立的信号只有两个：

1. 失败发生在加载期（load time），早于扩展渲染，且错误类型是TypeError；
2. 扩展的 bundler 配置没有把react/jsx-runtime列入externals映射。

根因：依赖间接引入的 JSX 运行时与 React 19 内部结构冲突

为什么仅仅缺少一个 externals 条目就会导致TypeError？原因在于依赖链的间接引用：许多第三方依赖（典型如antd）会直接 importreact/jsx-runtime。当 bundler 配置中没有将该模块外部化时，webpack 等构建工具就会把一份自己的react/jsx-runtime副本打进扩展 bundle。

这份内嵌的运行时副本会触达 React 内部对象，而 React 19 已经移除了该内部结构，于是与宿主实例（运行 React 19）产生冲突，最终在加载期抛出TypeError。换言之：问题不是扩展代码本身写错了，而是扩展 bundle 中混入了与宿主 React 19 不匹配的运行时副本。

修复方案：把react/jsx-runtime加入 externals

官方推荐的标准修复动作是在 bundler 配置的externals映射中新增react/jsx-runtime，让所有 JSX 运行时导入都解析到宿主在window.ReactJSXRuntime上暴露的运行时。以 webpack 为例：

// webpack.config.js externals: { react: 'React', 'react-dom': 'ReactDOM', 'react/jsx-runtime': 'ReactJSXRuntime', moment: 'Moment', }

修改完成后重新构建扩展。重建后，扩展将与宿主应用共享同一个 React 19 实例，从而恢复加载。

需要说明的是，外部化（externalize）策略本身就是 Argo CD UI 扩展的基本约束：扩展不应把 React 库打进自己的包，而应通过externals消费宿主提供的全局变量。旧版扩展通常只外部化了react，在 React 19 时代必须把react/jsx-runtime一并加入。

其他构建工具的等价写法

官方文档以 webpack 为例，其他支持 externals 语义的构建工具可以采用等价写法：

• Rollup（配合@rollup/plugin-node-resolve与 globals 映射）：将react/jsx-runtime的 global 指向ReactJSXRuntime，输出格式设为iife/umd，与react: 'React'、react-dom: 'ReactDOM'、moment: 'Moment'并列；
• Vite（库模式）：在build.rollupOptions.external中列出react、react-dom、react/jsx-runtime、moment，并相应配置output.globals。

无论使用哪种工具，核心原则一致：让 bundle 中不包含任何 React 相关模块的副本。

宿主 UI 暴露的全局模块清单

为了让扩展通过externals消费依赖，宿主 UI 目前在window上暴露以下模块（也是官方文档给出的完整清单）：

从源码可以印证这一暴露机制：在 ui/src/app/index.tsx 中，Argo CD UI 的入口文件在渲染根组件之后，将上述模块逐一挂到window上：

(window as any).React = React; (window as any).ReactDOM = ReactDOM; (window as any).Moment = Moment; (window as any).ReactJSXRuntime = require('react/jsx-runtime');

这四行代码正是扩展externals映射得以生效的底层支撑：打包后的扩展在运行时从window.React、window.ReactDOM、window.ReactJSXRuntime、window.Moment读取对应模块，而不再加载自己的副本。

升级后的自查与排错建议

完成配置修改并重新构建后，建议按以下顺序自查：

1. 确认 externals 生效：在构建产物中搜索react/jsx-runtime、react等关键字，确认这些模块没有被打包进 bundle（产物中不应出现require('react')之类的内联代码）。
2. 确认全局变量存在：扩展加载时机在宿主页面初始渲染之后，此时window.ReactJSXRuntime已被 ui/src/app/index.tsx 赋值；若扩展在更早阶段执行，可能读到undefined。
3. 对照报错信号：若仍报TypeError且 externals 已正确配置，问题大概率不再属于运行时外部化范畴，而是依赖版本与 React 19 的兼容性问题（见下文）。
4. 在真实环境验证：将重新构建的扩展文件放入argocd-serverPod 的/tmp/extensions目录（文件名需匹配^extension(.*)\.js$），刷新 Argo CD UI 页面确认扩展正常渲染。

仍无法加载？检查不兼容的依赖版本

外部化react/jsx-runtime只解决最常见的失败模式。如果扩展在完成上述修改后仍然加载失败，那么大概率是扩展所依赖的某个库版本自身与 React 19 不兼容。官方文档给出的处理方向是：将相应包升级到支持 React 19 的版本——绝大多数仍在积极维护的库都已提供 React 19 兼容版本。

识别不兼容依赖时，可以结合两点判断：

• 扩展成功通过TypeError加载期之后，却在渲染阶段抛错（例如Invalid hook call、Cannot read properties of undefined等），说明运行时副本问题已解决，剩余问题集中在依赖兼容性；
• 升级依赖时，优先关注扩展直接 import 的 UI 组件库（如antd及其 React 19 兼容版本antd@5.22+等）、以及任何传递依赖 React 内部 API 的库，逐个版本升级并回归验证。

参考案例：官方推荐的两份修复模板

官方文档列出了两份实际应用了该修复的 Pull Request，可作为其他扩展仓库的适配模板（文档仅给出链接，此处不再重复外部地址，可直接在对应仓库中按 PR 编号检索）：

• argocd-ephemeral-access 扩展的 PR #141：Ephemeral Access（临时访问）扩展的 React 19 适配示例；
• rollout-extension 的 PR #104：Argo Rollouts 扩展的适配示例。

这两个 PR 都体现了同一套修复模式：在 webpack（或等价工具）的externals中追加react/jsx-runtime: 'ReactJSXRuntime'，重新构建后扩展即可在 Argo CD 3.5+ 上正常加载。

小结

对于 Argo CD UI 扩展维护者来说，这轮升级的核心就一句话：外部化react/jsx-runtime，与宿主共享同一个 React 19 实例。完成这一改动并回归验证后，扩展即可在 Argo CD 3.5+ 的宿主 UI 中继续稳定运行。

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd