Back to Details

ln-711-npm-upgrader

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ln-711-npm-upgrader

ln-711-npm-upgrader

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader
Upgrades Node.js dependencies using npm, yarn, or pnpm with automatic breaking change detection and migration.
类型： L3 Worker 分类： 7XX 项目初始化 父级： ln-710-dependency-upgrader
使用npm、yarn或pnpm升级Node.js依赖项，支持自动检测破坏性变更并执行迁移。

Overview

概述

AspectDetails
InputProject path, package manager type
OutputUpdated package.json, lock file, migration report
Supportsnpm, yarn (classic & berry), pnpm
方面详情
输入项目路径，包管理器类型
输出更新后的package.json、锁文件、迁移报告
支持npm、yarn（经典版及berry版）、pnpm

Workflow

工作流

See diagram.html for visual workflow.
Phases: Pre-flight → Analyze → Security Audit → Check Outdated → Identify Breaking → Apply Upgrades → Apply Migrations → Verify Build → Report
查看diagram.html获取可视化工作流。
阶段： 预检 → 分析 → 安全审计 → 检查过期依赖 → 识别破坏性变更 → 执行升级 → 执行迁移 → 验证构建 → 生成报告

Phase 0: Pre-flight Checks

阶段0：预检

CheckRequiredAction if Missing
Lock file (package-lock.json, yarn.lock, pnpm-lock.yaml)YesWarn and run 
npm install
first
package.jsonYesBlock upgrade
Workers assume coordinator (ln-710) already verified git state and created backup.
检查项是否必填缺失时的操作
锁文件（package-lock.json、yarn.lock、pnpm-lock.yaml）是发出警告并先执行
npm install
package.json是阻止升级
工作器假设协调器（ln-710）已验证git状态并创建备份。

Phase 1: Analyze Dependencies

阶段1：分析依赖项

Read package.json and categorize dependencies for upgrade priority.
读取package.json并对依赖项分类，确定升级优先级。

Dependency Categories

依赖项分类

CategoryExamplesPriority
frameworkreact, vue, angular2 (after peer deps)
buildvite, webpack, esbuild3
ui@radix-ui/*, tailwindcss4
state@tanstack/react-query, zustand5
utilslodash, date-fns6
deveslint, prettier, typescript7
peer@types/*, typescript1 (first)
分类示例优先级
框架react, vue, angular2（在Peer依赖之后）
构建工具vite, webpack, esbuild3
UI组件库@radix-ui/*, tailwindcss4
状态管理@tanstack/react-query, zustand5
工具库lodash, date-fns6
开发依赖eslint, prettier, typescript7
Peer依赖@types/*, typescript1（优先处理）

Phase 2: Security Audit

阶段2：安全审计

Commands

命令

ManagerCommand
npm
npm audit --audit-level=high
yarn
yarn audit --level high
pnpm
pnpm audit --audit-level high
包管理器命令
npm
npm audit --audit-level=high
yarn
yarn audit --level high
pnpm
pnpm audit --audit-level high

Actions

处理动作

SeverityAction
CriticalBlock upgrade, report
HighWarn, continue
Moderate/LowLog only
严重程度操作
严重阻止升级并生成报告
高发出警告并继续
中/低仅记录日志

Phase 3: Check Outdated

阶段3：检查过期依赖

Commands

命令

ManagerCommand
npm
npm outdated --json
yarn
yarn outdated --json
pnpm
pnpm outdated --json
包管理器命令
npm
npm outdated --json
yarn
yarn outdated --json
pnpm
pnpm outdated --json

Phase 4: Identify Breaking Changes

阶段4：识别破坏性变更

Detection

检测方式

  1. Compare current vs latest major versions
  2. Check breaking_changes_patterns.md
  3. Query Context7/Ref for migration guides
  1. 对比当前版本与最新主版本
  2. 查看breaking_changes_patterns.md
  3. 通过Context7/Ref查询迁移指南

Common Breaking Changes

常见破坏性变更

See breaking_changes_patterns.md for full patterns.
PackageBreaking VersionKey Changes
react18 → 19JSX Transform, ref as prop
vite5 → 6ESM only, Node 18+
eslint8 → 9Flat config required
tailwindcss3 → 4CSS-based config
typescript5.4 → 5.5+Stricter inference
查看breaking_changes_patterns.md获取完整变更模式。
包破坏性变更版本主要变更
react18 → 19JSX转换、ref作为属性传递
vite5 → 6仅支持ESM、要求Node 18+
eslint8 → 9需要使用扁平配置
tailwindcss3 → 4基于CSS的配置
typescript5.4 → 5.5+更严格的类型推断

Phase 5: Apply Upgrades

阶段5：执行升级

Upgrade Order

升级顺序

  1. Peer dependencies (TypeScript, @types/*)
  2. Framework packages (React, Vue core)
  3. Build tools (Vite, webpack)
  4. UI libraries (after framework)
  5. Utilities (lodash, date-fns)
  6. Dev dependencies (testing, linting)
  1. Peer依赖（TypeScript、@types/*）
  2. 框架包（React、Vue核心库）
  3. 构建工具（Vite、webpack）
  4. UI组件库（框架升级完成后）
  5. 工具库（lodash、date-fns）
  6. 开发依赖（测试、代码检查工具）

Commands

命令

ManagerCommand
npm
npm install <package>@latest --save
yarn
yarn add <package>@latest
pnpm
pnpm add <package>@latest
包管理器命令
npm
npm install <package>@latest --save
yarn
yarn add <package>@latest
pnpm
pnpm add <package>@latest

Peer Dependency Conflicts

Peer依赖冲突

SituationSolution
ERESOLVE error
npm install --legacy-peer-deps
Still fails
npm install --force
(last resort)
场景解决方案
ERESOLVE错误执行
npm install --legacy-peer-deps
仍失败执行
npm install --force
（最后手段）

MCP Tools for Migration Search

迁移搜索用MCP工具

Priority Order (Fallback Strategy)

优先级顺序（降级策略）

PriorityToolWhen to Use
1mcp__context7__query-docsFirst choice for library docs
2mcp__Ref__ref_search_documentationOfficial docs and GitHub
3WebSearchLatest info, community solutions
优先级工具使用场景
1mcp__context7__query-docs库文档查询的首选工具
2mcp__Ref__ref_search_documentation官方文档与GitHub资源查询
3WebSearch获取最新信息、社区解决方案

Context7 Usage

Context7使用方法

StepToolParameters
1. Find librarymcp__context7__resolve-library-idlibraryName: "react", query: "migration guide"
2. Query docsmcp__context7__query-docslibraryId: "/facebook/react", query: "react 18 to 19 migration"
步骤工具参数
1. 查找库mcp__context7__resolve-library-idlibraryName: "react", query: "migration guide"
2. 查询文档mcp__context7__query-docslibraryId: "/facebook/react", query: "react 18 to 19 migration"

MCP Ref Usage

MCP Ref使用方法

ActionToolQuery Example
Searchmcp__Ref__ref_search_documentation"react 19 migration guide breaking changes"
Readmcp__Ref__ref_read_urlURL from search results
操作工具查询示例
搜索mcp__Ref__ref_search_documentation"react 19 migration guide breaking changes"
读取mcp__Ref__ref_read_url搜索结果中的URL

WebSearch Fallback

Web搜索降级方案

Use when Context7/Ref return no results:
  • "<package> <version> breaking changes migration 2025"
  • "<package> <error message> fix stackoverflow"
当Context7/Ref无结果时使用：
  • "<package> <version> breaking changes migration 2025"
  • "<package> <error message> fix stackoverflow"

Phase 6: Apply Migrations

阶段6：执行迁移

Process

流程

  1. Use MCP tools (see section above) to find migration guide
  2. Apply automated code transforms via Edit tool
  3. Log manual migration steps for user
Do NOT apply hardcoded migrations. Always fetch current guides via MCP tools.
  1. 使用MCP工具（见上文）查找迁移指南
  2. 通过Edit工具执行自动化代码转换
  3. 记录需要用户手动执行的迁移步骤
请勿使用硬编码的迁移逻辑，务必通过MCP工具获取最新指南。

Phase 7: Verify Build

阶段7：验证构建

Commands

命令

CheckCommand
TypeScript
npm run check
or 
npx tsc --noEmit
Build
npm run build
Tests
npm test
(if available)
检查项命令
TypeScript
npm run check
或 
npx tsc --noEmit
构建
npm run build
测试
npm test
（若存在）

On Failure

失败处理

  1. Identify failing package from error
  2. Search Context7/Ref for fix
  3. If unresolved: rollback package, continue with others
  1. 从错误信息中定位失败的包
  2. 通过Context7/Ref搜索修复方案
  3. 若无法解决：回滚该包，继续升级其他依赖

Phase 8: Report Results

阶段8：生成结果报告

Report Schema

报告结构

FieldDescription
projectProject path
packageManagernpm, yarn, or pnpm
durationTotal time
upgrades.major[]Breaking changes applied
upgrades.minor[]Feature updates
upgrades.patch[]Bug fixes
migrations[]Applied migrations
skipped[]Already latest
buildVerificationPASSED or FAILED
warnings[]Non-blocking issues
字段描述
project项目路径
packageManagernpm、yarn或pnpm
duration总耗时
upgrades.major[]已应用的破坏性变更
upgrades.minor[]功能更新
upgrades.patch[]Bug修复
migrations[]已执行的迁移
skipped[]已为最新版本的依赖
buildVerification构建验证结果（通过/失败）
warnings[]非阻塞性问题

Configuration

配置

yaml
Options:
  # Upgrade scope
  upgradeType: major          # major | minor | patch

  # Breaking changes
  allowBreaking: true
  autoMigrate: true
  queryMigrationGuides: true  # Use Context7/Ref

  # Security
  auditLevel: high            # none | low | moderate | high | critical
  minimumReleaseAge: 14       # days

  # Peer dependencies
  legacyPeerDeps: false
  force: false

  # Verification
  runBuild: true
  runTests: false
  runTypeCheck: true

  # Rollback
  createBackup: true
  rollbackOnFailure: true
yaml
Options:
  # 升级范围
  upgradeType: major          # 主版本 | 次版本 | 补丁版本

  # 破坏性变更
  allowBreaking: true
  autoMigrate: true
  queryMigrationGuides: true  # 使用Context7/Ref

  # 安全设置
  auditLevel: high            # 无 | 低 | 中 | 高 | 严重
  minimumReleaseAge: 14       # 天数

  # Peer依赖设置
  legacyPeerDeps: false
  force: false

  # 验证设置
  runBuild: true
  runTests: false
  runTypeCheck: true

  # 回滚设置
  createBackup: true
  rollbackOnFailure: true

Error Handling

错误处理

ErrorCauseSolution
ERESOLVEPeer dep conflict--legacy-peer-deps
ENOENTMissing lock filenpm install first
Build failBreaking changeApply migration via Context7
Type errorsVersion mismatchUpdate @types/*
错误原因解决方案
ERESOLVEPeer依赖冲突使用--legacy-peer-deps参数
ENOENT缺少锁文件先执行npm install
构建失败存在破坏性变更通过Context7应用迁移方案
类型错误版本不兼容更新@types/*包

Rollback

回滚

Restore package.json and lock file from git, then run clean install to restore previous state.
从git恢复package.json和锁文件，然后执行干净安装恢复到之前的状态。

References

参考资料

  • breaking_changes_patterns.md
  • npm_peer_resolution.md
Version: 1.1.0 Last Updated: 2026-01-10
  • breaking_changes_patterns.md
  • npm_peer_resolution.md
版本： 1.1.0 最后更新： 2026-01-10