Next.js 14 到 15 自动化升级全流程以 next/codemod upgrade 的 React 19 迁移夹具为切入点【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.jsnext/codemod upgrade是 Next.js 官方为「从一个大版本平滑升级到下一个大版本」设计的自动化 CLI它先探测项目当前安装的 Next.js 与 React 版本再依次完成依赖版本解析、交互式确认、语义化 codemod 批量改写以及安装执行。本文以 packages/next-codemod/bin/testfixtures/next-14-installed/README.md测试夹具的期望输出快照为核心骨架结合upgrade子命令的真实实现与相关 transform 源码完整还原「Next.js 14 React 18 项目升级到 Next.js 15 React 19」时工具会做什么、为什么这么做以及每步改动在 package.json 中留下的痕迹。读完后你将能预判升级工具的全部行为并在自己的项目上安全地复现同样的迁移。1. 这篇文档是什么一份「升级行为」的黄金快照next-14-installed是 packages/next-codemod 测试夹具目录之一它描述了一个起始版本明确、升级行为可预期的典型场景。目录里只有三个文件package.json夹具的「迁移前」状态即一个依赖next14.3.0-canary.44、react18.2.0、react-dom18.2.0、types/react^18.2.0、types/react-dom^18.2.0的最小项目pnpm-workspace.yaml空文件用于模拟 pnpm 项目中的 workspace 声明README.md这份关联文档本身它以「行为清单 package.json diff」的形式记录了升级工具在这一夹具上的全部预期动作与最终输出属于验证upgrade流程的黄金快照。因此这份 README 的价值不在其篇幅而在于它精确刻画了官方对「Next.js 14 老项目升 15」的完整自动化策略。下面逐一对照 upgrade 主流程实现 展开。2. 升级起始状态一个典型的 Next.js 14 React 18 项目夹具的迁移前package.json如下{ name: next-14-installed, scripts: { dev: next dev }, dependencies: { next: 14.3.0-canary.44, react: 18.2.0, react-dom: 18.2.0, types/react: ^18.2.0, types/react-dom: ^18.2.0 } }它同时代表了几层含义版本探测依据升级入口runUpgrade首先通过require.resolve(next/package.json)读取当前安装的 Next.js 版本见 upgrade.ts 中getInstalledNextVersion若在 monorepo 根目录找不到会抛出BadInput提示应到具体 app 目录执行。React 18 是「历史包袱」夹具中 React 仍是 18.2.0这是升级工具需要重点决策的分支点。没有 app/pages 目录夹具项目既不含app也不含pages目录因此在后面提到的「是否停留在 React 18」询问中不满足纯 App Router条件会走交互式确认分支。值得注意该版本组合next14.3.0-canary.44是刻意选择的临界点——从14.3.0-canary.45起 Next.js 的 peer 依赖要求 React 版本为19.0.0-beta.0源码注释中给出了 PR/Release 引用意味着任何低于此版本的 Next.js 14 项目在升级后都将面对 React 大版本跳变。3. README 记录的五大升级动作逐一拆解夹具 README 开头的 5 行即升级工具对该场景输出的全部交互与建议Prompts for React 19 upgrade with a recommendation to do so提示升级 React 19 并给出推荐Suggests adding--turbopacktonext devscript建议给 dev 脚本追加--turbopackSuggestsapp-dir-runtime-config-experimental-edgetransformSuggestsnext-async-request-apitransformSuggestsnext-request-geo-iptransform下面逐条对应到runUpgrade的执行顺序。3.1 React 19 升级询问哪些项目会问、哪些项目直接升对应实现位于 upgrade.ts 的 React 分支判断逻辑触发条件同时满足目标 Next.js 版本 14.3.0-canary.45compareVersions(targetNextVersion, 14.3.0-canary.45) 0当前安装的 React 版本以18开头不是纯 App Router 项目即没有只存在app目录而完全不存在pages目录。若项目是纯 App Router工具直接视为必须使用 React 19不弹窗若项目同时使用 pages 和 app混合模式询问文案会额外提示 we recommend upgrading React to use a consistent version throughout your app即推荐统一到 React 19。夹具项目两者目录都没有故满足弹窗条件交互结果默认不留在 React 18initial: false。而shouldStayOnReact18 true时React 被固定在18.3.1React 18 的最后一个 minor 版本否则通过loadHighestNPMVersionMatching以react目标next的peerDependencies.react为查询条件去 npm registry 解析最高匹配稳定版例如夹具中最终落到了19.0.0。3.2 建议给next dev追加--turbopack仅当目标版本落在 15.0.0-canary 16.0.0-canary区间时suggestTurbopack才会触发。它的三段式启发逻辑源码注释写得很清楚是dev 脚本已含--turbopack→ 什么都不做dev 脚本含next dev→ 询问是否启用 Turbopack非交互模式默认启用然后替换为next dev --turbopackdev 脚本不含next dev→ 提示用户手动把启动参数加进自定义命令。夹具项目 dev 脚本就是最普通的dev: next dev因此匹配第 2 条路径得到建议追加--turbopack这一行为。一个容易被忽略的细节是 flag 的命名分界从v15.0.1-canary.3PR #71657起 Turbopack 标志从--turbo改为--turbopack。因此若项目从旧版本升上来且 dev 脚本里还残留--turbo工具会自动把它替换成--turbopack——夹具 README 输出使用--turbopack正是因为目标版本15.0.4-canary.43已越过该分界点。3.3 三个被推荐的 codemod 是怎么被选出来的升级工具不会一股脑运行所有 codemod而是依据统一的 codemod 注册表TRANSFORMER_INQUIRER_CHOICES做区间过滤只推荐「版本介于当前 Next.js 版本与目标版本之间」的 transform。每个注册项都带一个version字段代表该 codemod 从哪个 Next.js 版本起生效。注册表注释特别强调新增 codemod 时务必填写目标 canary 版本而非稳定版这样从 canary 升 canary 时也能被正确命中。以夹具为例当前14.3.0-canary.44目标15.0.4-canary.43注册表中恰好落在该区间内的三项是codemod value注册版本作用next-request-geo-ip15.0.0-canary.153安装vercel/functions以替代NextRequest上的geo/ip属性next-async-request-api15.0.0-canary.171改写 Next.js 异步 Request API 的用法app-dir-runtime-config-experimental-edge15.0.0-canary.179把 Route Segment Config 的runtime: experimental-edge转为edge而注册表中紧随其后的next-experimental-turbo-to-turbopack15.4.2-canary.21高于目标版本15.0.4-canary.43所以不会被推荐——这解释了为何 README 恰好只列了三项。交互模式下会以多选框呈现默认全部选中非交互--yes或非 TTY模式则按注释所言 Every prompt will accept its default全部应用。3.4 三个 transform 到底改了什么源码佐证app-dir-runtime-config-experimental-edge实现见 app-dir-runtime-config-experimental-edge.ts。它先用正则/[/\\]app[/\\].*?(page|layout|route)\.[^/\\]$/限定只处理 App Router 的page/layout/route文件再定位名为runtime的具名导出把字符串字面量experimental-edge替换为edgeruntimeValue.replaceWith(j.stringLiteral(edge))测试用例见 app-dir-runtime-config-experimental-edge.test.js。这是 Next.js 15 中experimental-edgeruntime 命名收敛为edge的自动改写。next-async-request-api入口见 next-async-request-api.ts它把具体逻辑转发到lib/async-request-api/配套测试有 next-async-request-api-dynamic-apis.test.js 与 next-async-request-api-dynamic-props.test.js。对应 Next.js 15 中cookies()、headers()、draftMode()等请求相关 API 全面异步化的迁移把旧的同步取值改为await调用。next-request-geo-ip实现见 next-request-geo-ip.ts。Next.js 15 将NextRequest上内置的geo/ip请求信息迁移到独立包vercel/functions该 transform 负责把以下形态全部改写为函数调用req.geo/req.ip→geolocation(req)/ipAddress(req)解构const { geo, ip } req→ 拆成独立声明const geo geolocation(req)NextRequest[geo]/NextRequest[ip]类型访问 → 换成vercel/functions的类型geolocation/ipAddress命名空间下并自动补 import。测试见 next-request-geo-ip.test.js。4. package.json 的最终 diff从 14 canary 到 15 canary React 19夹具 README 用一段完整 diff 展示了升级后package.json的变化这也是该场景的核心产物原样继承如下diff --git a/packages/next-codemod/bin/__testfixtures__/next-14-installed/package.json b/packages/next-codemod/bin/__testfixtures__/next-14-installed/package.json index 5ec4c37f0b..131f5b9f4a 100644 --- a/packages/next-codemod/bin/__testfixtures__/next-14-installed/package.json b/packages/next-codemod/bin/__testfixtures__/next-14-installed/package.json -4,10 4,16 dev: next dev }, dependencies: { - next: 14.3.0-canary.44, - react: 18.2.0, - react-dom: 18.2.0, - types/react: ^18.2.0, - types/react-dom: ^18.2.0 next: 15.0.4-canary.43, react: 19.0.0, react-dom: 19.0.0, types/react: 19.0.0, types/react-dom: 19.0.0 }, pnpm: { overrides: { types/react: 19.0.0, types/react-dom: 19.0.0 } } }这段 diff 可以从 upgrade.ts 的实现中逐一验证版本映射表versionMappingnext、react、react-dom是required: true只要项目里声明过就会写入react-is与optionalNextjsPackageseslint-config-next、next/mdx、next/env、next/third-parties等共 15 个为可选依赖仅当项目中已存在时才跟随升级到同一版本。工具遍历后调用addPackageDependency写入并统一以JSON.stringify(..., null, 2) 换行符落盘。精确版本而非范围代码注释解释了原因——直接把peerDependencies里类似^18.2.0 || ^19.0.0 || 20.0.0-canary这种丑陋的区间写进 manifest 会污染依赖声明因此统一先解析出最高匹配的精确版本。types/react/types/react-dom落到精确的19.0.0对于稳定版 React 分支工具以types/reactreact 的 peerDependencies查询 npm 并取最高版本代码注释提到https://github.com/microsoft/DefinitelyTyped-tools/issues/433的隐患因此即便只有 alias 需求也会把类型包加入 overrides 兜底。4.1 overrides 字段按包管理器分流的底层实现diff 最后新增的pnpm.overrides不是随便写的writeOverridesField会根据探测到的包管理器选择字段落点upgrade.ts包管理器写入位置npmpackage.json#overridespnpmv10 及以下已有resolutions则并入否则写入package.json#pnpm.overridespnpmv11 及以上或版本不可探测改写入pnpm-workspace.yaml#overrides见writePnpmWorkspaceOverrides延迟require(js-yaml)同步读写yarnpackage.json#resolutionsbun已有resolutions则并入否则写入package.json#overrides夹具 README 展示的是 pnpm 且落在 v11 之前的行为写入package.json#pnpm.overrides仓库里同目录的兄弟夹具 pnpm-v11-overrides 则专门验证了 pnpm v11 场景——此时pnpm.overrides会被 pnpm v11 静默忽略必须写到pnpm-workspace.yaml#overrides。源码注释给出了依据pnpm v11 起 canonical 位置迁移到pnpm-workspace.yaml#overrides并对无法探测的版本默认按 v11 布局处理。5. 升级的完整链路与配套的 React 19 生态工具依赖写入并runInstallation完成后工具会依次执行三件事upgrade.ts对第 3.3 节选出的 codemod 逐个调用runTransform(codemod, cwd, { force: true, verbose, nonInteractive })应用改写若选择了 React 19 升级再调用codemodlatest react/19/migration-recipe --no-interactive --allow-dirtyReact 官方 React 19 迁移 recipe--allow-dirty是必需的因为前面已修改了 package.json 与 lockfilerecipe 拒绝在脏工作区运行调用types-react-codemodlatest --yes preset-19 .处理 React 19 的 TypeScript 类型变更这两个外部命令根据包管理器选择npx --yes/pnpm --silent dlx/yarn --quiet dlx/bunx。收尾阶段还会尽力刷新项目根AGENTS.md/CLAUDE.md中由工具托管的 agent-rules 块使其与新版本匹配刷新逻辑见 agents-md.ts该动作是 best-effort失败不会中断升级随后warnDependenciesOutOfRange会扫描node_modules下直接依赖的peerDependencies把与升级后版本不兼容的依赖以✕ unmet peer树形结构打印出来。6. 在自己的项目上复现这套升级要复现夹具描述的流程只需在目标项目根目录执行npx next/codemod upgrade关键选项与行为均来自 upgrade.ts 的runUpgrade签名revision 参数可传具体版本号、dist-taglatest/canary/rc或语义关键字语义关键字在resolveSemanticRevision中解析——patch→~主.次.0当前 minor 内最新补丁、minor→^主.0.0当前 major 内最新 minor、major→latest默认值为minor。非法输入会抛出BadInput并列出可用版本。--yes/ 非 TTY进入非交互模式所有提示取默认值React 18 默认不保留、推荐 codemod 全部应用。--verbose打印Resolved upgrade target与Target version等中间信息便于排查。命令须在包含package.json的 Next.js 应用目录下运行monorepo 场景需切到具体 app 目录否则版本探测会失败。工具最后会输出一段结束语要求人工复核本地改动并按提示阅读 Next.js 15 迁移指南完成迁移的剩余部分endMessage中major(targetNextVersion) 15分支——这提醒我们codemod 只能完成机械改写路由、数据请求方式等语义层面的最终确认仍需人工 review。7. 小结从一份夹具快照读懂官方升级策略next-14-installed夹具看似只是几行行为描述与一段 diff但它完整浓缩了 Next.js 官方对老项目跨大版本升级的工程化策略以注册版本做 codemod 区间过滤、以 peerDependencies 做依赖精确解析、以包管理器差异做 overrides 落点分流、再叠加 React 官方迁移工具链。对照 upgrade.ts 与 lib/utils.ts 阅读你不仅能预判工具在任意版本组合下的行为也能在遇到为什么升级后多出 pnpm.overrides为什么某个 codemod 没被推荐这类问题时直接从源码中找到答案。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考