智能依赖冲突检测与解决方案

依赖冲突总览

• 冲突数量统计
  • 严格版本/peer 冲突：2
  • 兼容性风险（非阻塞）：3
• 严重程度分布
  • 高：1（运行时核心依赖冲突）
  • 中：1（测试链路缺失 peer 依赖）
  • 低：3（构建/运行环境与 ESM/覆盖策略等兼容性风险）
• 影响范围分析
  • 运行时 UI：受 legacy-widget 与 React 版本不兼容影响，风险高，涉及所有使用该组件的功能
  • 测试链路：babel-jest 缺少 @babel/core，可能导致单测无法运行
  • 构建与本地开发：webpack-sources 覆盖策略在特定插件组合下有潜在不兼容；immer 10 的 ESM 属性在 Jest 环境下需要额外转译配置
  • 多环境一致性：engines 限制为 >=16 <20，使用 Node 20 的环境可能产生安装或运行差异

详细冲突列表

1. 冲突包名称和当前版本

   • legacy-widget@2.0.1
   • 关联包：react@^18.2.0, react-dom@^18.2.0 冲突类型
   • 直接冲突（peerDependencies 不满足） 详细说明
   • legacy-widget 的 peerDependencies: react ^17.0.0
   • 项目实际安装：react 18.x，超出其声明的兼容范围 兼容性风险等级
   • 高 影响的功能模块
   • 所有使用 legacy-widget 的页面与功能；可能引发 Hooks 失效、生命周期差异、行为变更（React 18 并发相关、自动批处理、严格模式变化等） 推荐解决方案
   • 首选：升级 legacy-widget 至明确声明支持 React 18 的版本（peerDependencies 中包含 react >=18 的版本）。在升级前确认破坏性变更与迁移指南。
   • 备选：若无可用升级版本，考虑将项目 React 降级至 17（影响范围见风险评估），或将 legacy-widget 以独立微前端/iframe 隔离运行在 React 17 环境，避免在同一个 React 实例中混用。

2. 冲突包名称和当前版本

   • babel-jest@^29.7.0 冲突类型
   • 传递/peer 冲突（缺失必要 peer） 详细说明
   • babel-jest 对 @babel/core 存在 peerDependencies（^7.8.0），当前 devDependencies 中未声明 @babel/core 兼容性风险等级
   • 中 影响的功能模块
   • 单元测试与任何依赖 babel-jest 的测试/转译流程 推荐解决方案
   • 在 devDependencies 中补齐 @babel/core（7.x 主版本范围，满足 babel-jest peer 要求），并确保 Babel 配置包含对 JSX/TypeScript 的处理（如 @babel/preset-react、@babel/preset-typescript，根据现有测试配置选择性启用）。

3. 风险项（兼容性，非严格冲突）：immer@^10.0.0 为 ESM-only 冲突类型

   • 兼容性风险（测试/转译配置） 详细说明
   • Immer 10 为 ESM-only。Webpack 5 构建通常无碍，但在 Jest 29 + babel-jest 环境下，如未允许对 node_modules 的 ESM 包进行转译，可能出现导入错误 兼容性风险等级
   • 低（可通过配置消解） 影响的功能模块
   • 测试环境下的使用 immer 的模块 推荐解决方案
   • 在 Jest 配置中允许 ESM 依赖转译（例如调整 transform 与 transformIgnorePatterns），并确保 Babel 配置对 ESM/TS/JSX 处理完善；或在需要时切换至支持 ESM 的测试转译策略（如 ts-jest 的 ESM 模式，或确保 babel-jest 转译覆盖 immer）。

4. 风险项（兼容性，非严格冲突）：engines 设置为 "node": ">=16 <20" 冲突类型

   • 环境兼容性风险 详细说明
   • 若团队或 CI/CD/生产环境使用 Node 20，将出现安装警告或在启用严格 engines 检查时阻断安装 兼容性风险等级
   • 低-中（取决于实际使用的 Node 版本） 影响的功能模块
   • 安装/构建全流程；多环境一致性 推荐解决方案
   • 短期：统一团队与 CI 的 Node 版本至 LTS 16/18；在包管理配置中避免启用严格 engines 阻断（若有）。
   • 中期：在完成兼容性验证后再放宽 engines 至覆盖 Node 20，避免未验证即扩大范围。

5. 风险项（兼容性，非严格冲突）：overrides 强制 webpack-sources@^3.2.3 冲突类型

   • 依赖覆盖策略导致的潜在不兼容 详细说明
   • Webpack 5 与其官方插件链通常兼容 webpack-sources v3，但如引入依赖于 v1/v2 的第三方插件/loader，可能在构建期出现不兼容 兼容性风险等级
   • 低（现有依赖多为 Webpack 5 生态，通常安全） 影响的功能模块
   • 构建流程（尤其是引入额外的第三方插件后） 推荐解决方案
   • 保留该 overrides，但在引入新构建插件时进行一次依赖兼容审查；如发现对旧版 webpack-sources 的刚性依赖，再局部豁免覆盖或替换插件。

升级建议

• 安全升级路径
  • 路径 A（优先）：升级 legacy-widget 至支持 React 18 的版本
    • 选择原则：官方发布说明中明确 peerDependencies: react >=18 的版本；优先选择稳定分支的最新小版本
    • 同时确保其使用的 ReactDOM API 兼容 createRoot/render 的差异
  • 路径 B（兜底）：将 React 与 react-dom 降级至 17.x，并配套调整类型定义
    • 影响包同步：@types/react、@types/react-dom 同步调整至 17 对应版本
    • 其余关键依赖（antd 5、react-router-dom 6、zustand 4、redux 4、webpack 5）在 React 17 下仍处兼容范围
  • 测试链路修复：为 babel-jest 补齐 @babel/core（7.x 主版本）
  • 测试环境 ESM 支持：为 Immer 10 配置 Jest/Babel 的 ESM 转译
• 版本迁移步骤
  1. 选定路径：
     • 若选 A：在测试分支上升级 legacy-widget 至支持 React 18 的版本，更新锁定文件并完成构建
     • 若选 B：在测试分支上将 react/react-dom 固定至 17.x，同步调整 @types/react 与 @types/react-dom 至 17，对涉及 React 18 API 的调用进行替换（如 createRoot → ReactDOM.render 或适配方案）
  2. 修复测试链路：
     • 在 devDependencies 中声明 @babel/core（7.x），并确认 Babel/Jest 转译覆盖 TS/JSX 与 ESM 依赖（包括 immer）
  3. 全量构建与本地验证：
     • 本地开发环境启动、构建产物对比体积与警告项
  4. 预发验证：
     • 在预发环境对使用 legacy-widget 的页面做回归测试
  5. 如无新增构建插件，保留 webpack-sources 覆盖；若新增插件引发冲突，评估局部豁免覆盖
• 验证方法
  • 静态检查：安装阶段观察 peerWarnings；确保无 legacy-widget 与 react 的 peer 警告
  • 单元测试：运行全量测试，重点验证使用 immer 的用例在 Jest 下可运行
  • 集成测试：覆盖所有包含 legacy-widget 的页面/交互（挂载/卸载、状态更新、路由切换）
  • 构建与运行：产物体积、构建时警告（React 18 render 警告、ESM 转译警告）
• 回滚方案
  • 在变更前保留当前锁定文件和依赖快照
  • 路径 A 失败（升级 legacy-widget 不可行）：回滚至原版本链，并切换到路径 B（React 17）
  • 路径 B 失败（降级 React 影响范围过大）：回滚 React 版本，并转为微前端/iframe 隔离 legacy-widget 的方案
  • 如测试链路调整导致不稳定，回退 Jest/Babel 配置至原始状态并逐项恢复

风险评估

• 实施风险分析
  • 路径 A（升级 legacy-widget）
    • 风险：组件 API 或行为变更；样式与交互差异
    • 影响范围：仅使用 legacy-widget 的功能模块为主
  • 路径 B（降级 React 到 17）
    • 风险：丧失 React 18 的特性（并发/自动批处理等）；与现有代码的 API 差异需适配
    • 影响范围：全局 UI 层；需同步调整类型定义与可能的入口挂载逻辑
  • 测试链路（@babel/core 与 ESM 转译）
    • 风险：测试工具链配置漂移导致短期不稳定
    • 影响范围：CI 测试阶段；不影响生产运行
  • engines 设置
    • 风险：团队成员或 CI 使用 Node 20 触发安装/运行不一致
    • 影响范围：安装与构建阶段
  • overrides（webpack-sources）
    • 风险：未来引入的个别旧插件不兼容 v3
    • 影响范围：构建阶段，问题可通过替换插件或局部豁免解决
• 测试建议
  • 单测：确保对 legacy-widget 进行挂载/更新/卸载的行为测试；对 immer 相关逻辑的读写与不可变性测试
  • 端到端：覆盖包含 legacy-widget 的关键业务流程与跨路由切换
  • 浏览器兼容：至少在两种主流浏览器与移动端模拟器验证渲染和交互
  • 构建校验：对比变更前后产物体积与构建日志，检查 React 相关警告
• 监控指标
  • 运行时错误率（Sentry/前端日志中的 React 异常、Invalid hook call、渲染警告）
  • 交互性能指标（TTI、FCP、Long Tasks）在包含 legacy-widget 的页面是否退化
  • 构建阶段告警数（peerWarnings、ESM 转译告警）
  • 组件层 Telemetry（如可用）：legacy-widget 相关事件成功率与异常率

附注与说明

• 关于 webpack-dev-server@4.15.0：其 peerDependencies 为 webpack ^5，当前 webpack@^5.91.0 可满足，未发现冲突
• antd@5.12.0 对 React 的版本要求为 >=16.9.0，兼容 React 17/18，非冲突源
• 本报告所有建议基于公开的 semver 兼容性与常见工具链要求；未对未提供的私有包或外部未明示版本做推断。