メニュー
将一个 Modern.js 2.0 应用迁移到 3.0，优先做可安全自动化的依赖/配置/入口/import 改写，剩余复杂项收敛为人工清单。在「升级 Modern.js 大版本、modern.config 报废弃、要从 webpack/pages 迁到 Rspack/routes、自定义 server 报错」时使用。
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/web-infra-dev/modern.js --skill modernjs-migrate-to-v3コマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SOC 職業分類に基づく
SKILL.md を表示中
| name | modernjs-migrate-to-v3 |
| description | 将一个 Modern.js 2.0 应用迁移到 3.0，优先做可安全自动化的依赖/配置/入口/import 改写，剩余复杂项收敛为人工清单。在「升级 Modern.js 大版本、modern.config 报废弃、要从 webpack/pages 迁到 Rspack/routes、自定义 server 报错」时使用。 |
本 skill 用于单个 Modern.js 应用的 v2→v3 迁移。目标：完成可安全改写的部分，剩余风险收敛成明确人工清单。规则与示例以仓库 guides/upgrade/* 的真实文档为准。
projectDir，所有修改仅限 projectDirreferences/；仅在命中人工项时按需加载references/commit-changes.md）[X/6] 开始/完成/跳过/失败git -C <projectDir> status --porcelain
工作区非空时停止，提示先 git commit/git stash。建议在干净分支或 worktree 上迁移，便于回滚。
node scripts/scan-project.mjs <projectDir>
产出 <projectDir>/.agents/runs/modernjs-migrate/context.json：判定 v2/v3、Node 版本、入口类型、命中的 features 与 v2Signals。脚本失败（非 v2/v3、Node 过低）时直接停止并展示原因。migrationState=v3 按续迁移处理。
monorepo / workspace 项目：
@modern-js/app-tools用workspace:*/link:/catalog:等协议时无法从版本号判定大版本。此时只有命中v2-only 结构信号（顶层runtime、appTools({ bundler })、applyBaseConfig、@modern-js/plugin-tailwindcss、@modern-js/runtime/bff|serverimport、、、自定义 ）才判为 v2；（非 0 退出、不写 context），避免把已是 v3 的 workspace 应用误迁。 / / 不算 v2 信号（v3 也有）。
App.config/initsrc/pagesserver/indexroutessrc/modern.runtime.tsappTools()约定式路由红线：
entryType=routes时，src/routes/page.*和src/routes/layout.*是 v3 标准结构，必须保留。不要把page.tsx改名为index.tsx，不要把layout.tsx挪到legacy-*，不要凭空生成src/entry.*或src/legacy-app/src/legacy-routes。如需处理routes/layout的config/init导出，只迁运行时配置逻辑，不改路由文件命名。
node scripts/migrate.mjs <projectDir>
自动完成（依据 guides/upgrade/*）：
workspace/link/catalog 协议 + 无任何 v2-only 信号 → 直接中止（exit 1，不改任何文件），不依赖 scan--to 时会通过 npm 检测 @modern-js/app-tools@3 的最新稳定 v3 版本作为目标版本；只有需要锁定版本时才显式传 --to=<version>。如果当前环境无法访问 npm registry，脚本会中止并提示显式传入目标版本，不会回退到 3.0.0。^2.x）的 @modern-js/* 升到检测到的最新 v3 目标版本；workspace/link/catalog 协议依赖保留不改（随 monorepo 整体升级，进人工清单）；移除 @modern-js/plugin-tailwindcssdefineConfig({}) / defineConfig<'rspack'>({}) / export default {} / module.exports = {}（JS 静态配置）均按主路径处理；函数式/动态 defineConfig(() => ({})) 含 runtime 时进人工清单@modern-js/runtime/bff→@modern-js/plugin-bff/client、@modern-js/runtime/server→@modern-js/server-runtime，并补充对应依赖（@modern-js/plugin-bff / @modern-js/server-runtime；版本协议：普通 semver 用目标版本；workspace: / catalog:（名称无关）沿用现有 app-tools/runtime 的 spec；link: / file: / portal: / npm:（指向具体包路径/别名）不照搬、进人工清单）；命中 BFF 时给 modern.config 顶层 plugins 末尾追加 bffPlugin()（保持 [appTools(), bffPlugin()] 顺序；必要时在 @modern-js/app-tools import 上补 appTools；无法补则进人工清单，不写半成品）eachModuleSpecifier，覆盖 import/export-from/side-effect import/import()/require()，含 import(/* magic */ '...') 这类带注释的动态 import）；dev/server 只在配置对象顶层迁移（嵌套 tools.dev.port 不动）；tailwind 仅删真实 import 行与真实 tailwindcssPlugin() 调用（按真实 specifier offset，不伤普通字符串/注释示例，移除后清理悬挂逗号）；注释/普通字符串里的 defineConfig/runtime/appTools({ bundler })/applyBaseConfig/dev: { port }/@modern-js/runtime/bff|server 都不会被误当真实配置、v2 信号或 import；需要字符串「值」的判断（如 ssr.mode）才保留字符串appTools({ bundler })→appTools()（v3 默认 Rspack，只删 bundler 参数）；modern.config 顶层 runtime 块 → 合并进 src/modern.runtime.ts（v3 不再支持在 config 配 runtime；只合并进空的 defineRuntimeConfig({})，非空/函数式进人工清单不覆盖）；dev.port→server.port（只移顶层 port，保留 dev 块其余字段；嵌套如 dev.client.port 不动）；移除 tailwind 插件并写 postcss.config.cjsguides/upgrade/config.mdx，结构化逐项）：output.cssModuleLocalIdentName→output.cssModules.localIdentName、disableCssExtract→injectStyles、disableFilenameHash/disableMinimize/disableSourceMap→filenameHash/minify/sourceMap（布尔取反）、enableInlineScripts/enableInlineStyles→inlineScripts/inlineStyles；source.moduleScopes/enableCustomEntry/disableEntryDirs 移除，resolveMainFields/resolveExtensionPrefix、output.enableLatestDecorators=true 进人工；html.appIcon 字符串→{ icons:[{src,size:180}] }、disableHtmlFolder→outputStructure、xxxByEntries 进人工；tools.webpack→rspack、webpackChain→bundlerChain、devServer 进人工（拆 dev.*）。非布尔/非字面量值不静默改、进人工@modern-js/plugin-server 依赖 + serverPlugin() 调用 + import；server/index.* 有 unstableMiddleware/afterRender 时 → 生成可构建的 server/modern.server.* 骨架（空 defineServerConfig，原逻辑作为注释保留），Hono Context 语义迁移进人工清单src/index.*→src/entry.*（bootstrap 箭头或函数声明形态都改写为 createRoot()/render()；无法识别的 bootstrap 形态进人工、不假装成功）；App.config 抽取到 src/modern.runtime.ts（已存在则不覆盖，进人工清单）useRuntimeContext() → React 19+ 用 use(RuntimeContext)、<19 用 useContext(RuntimeContext)（保留 react default/namespace import；useRuntimeContext as 别名 进人工清单不假改写）src/pages→src/routes（无 routes 时），并按 v3 约定把 pages/index.* 映射为 routes/page.*、pages/foo/index.* 映射为 routes/foo/page.*，同步改写相对 import 引用，残留进人工清单；迁移产物中禁止出现 routes/**/index.* 作为页面文件；缺根 routes/layout.* 时自动生成最小 Outlet 布局（v3 约定式路由需根布局）package.json 中调用 modern new / modern upgrade 的 scripts（v3 已移除这两个命令）
applyBaseConfig(...)包装的配置（仓库 integration 测试 helper / 非标准用户配置）：runtime/plugins/dev.port/appTools bundler等结构性迁移一律进人工清单（报告标注「结构迁移未完成」），只做依赖升级 / import 路径 / tailwind 移除等文件级安全改写，不在包装内半自动改坏配置。package.json的modernConfig.runtime同样进人工清单。
完成后查看 .agents/runs/modernjs-migrate/report.json 的 changed / manual。本步骤成功后执行 references/commit-changes.md。
依据 report 的 manual 列表，命中哪项读哪份：
| 人工项 | 参考 |
|---|---|
App.init / routes/layout 的 config/init 导出、modernConfig.runtime、非空/函数式 runtime | references/migrate-entry.md |
自定义 Web Server（unstableMiddleware / afterRender） | references/migrate-custom-server.md |
html.appIcon 字符串、server.ssr.mode、webpack 自定义配置、applyBaseConfig(...) 结构性迁移 | references/migrate-config.md |
useRuntimeContext as 别名 调用 | references/migrate-entry.md |
每处理完一项执行 references/commit-changes.md。
bash scripts/install-deps.sh <projectDir>
锁文件变更后执行 references/commit-changes.md（带 --include-lockfiles）。
bash scripts/run-lint.sh <projectDir>
失败记录后继续，不视为迁移失败。
跑 modern build（必要时关键路由 smoke）。最终报告：成功步骤、跳过项、失败项、人工处理项、后续建议。
pnpm-lock.yaml / dist / CHANGELOG / node_modules / secret。