跳转到内容
@aws/nx-plugin
Blog

升级您的工作空间

@aws/nx-plugin 提供了迁移功能，当您升级它时，会使用 nx migrate 自动更新您的工作空间。

升级 @aws/nx-plugin

Section titled “升级 @aws/nx-plugin”

首先，运行以下命令来更新插件版本并准备迁移：

Terminal window
pnpm nx migrate @aws/nx-plugin@latest
 
 NX   The migrate command has run successfully.


- package.json has been updated.
- migrations.json has been generated.
- 1 AI migration prompt(s) have been written to tools/ai-migrations/.


 NX   Next steps:


- Make sure package.json changes make sense and then run 'pnpm install --no-frozen-lockfile',
- Review and tweak the AI migration prompts in tools/ai-migrations/ as needed.
- Run 'pnpm exec nx migrate --run-migrations'
- To learn more go to https://nx.dev/features/automate-updating-dependencies

查看 package.json 的更改，然后安装：

Terminal window
pnpm install

然后运行迁移：

Terminal window
pnpm nx migrate --run-migrations

确定性迁移

Section titled “确定性迁移”

大多数迁移都是确定性的代码修改 — 它们无人值守运行，并报告任何故意跳过的内容：

 NX   Running migrations from 'migrations.json'


Running the following migrations:
- @aws/nx-plugin: update-vitest-workspace-config — Add a coverage reporter to vitest configs
- @aws/nx-plugin: update-custom-api-handlers — Update custom API handlers for the new middleware signature


── Migration 1 of 2 · @aws/nx-plugin:update-vitest-workspace-config ─────
→ Running generator…
Changes:
  UPDATE packages/api/vite.config.mts


...


 NX   Successfully finished running migrations from 'migrations.json'.


2 migrations applied, 0 commits created.


 NX   Some migrations have additional information, see below.


- packages/website/vite.config.mts has a customised shape; add a coverage reporter manually.

注意末尾的附加信息：当迁移发现您自定义的文件超出了它可以安全更新的范围时，它会保留您的更改，并在那里报告需要手动跟进的内容。

代理迁移

Section titled “代理迁移”

一些迁移针对您拥有的代码，其中正确的编辑取决于您构建的内容 — 这些作为提示由您本地的 AI 编码代理（Claude Code、Codex 或 OpenCode）应用。当有任何待处理时，Nx 会在涉及代理之前请求同意：

? Enable the agentic flow? …
❯ Yes, just this time      Apply 1 prompt migration and validate generator output with an AI agent
  Yes, always              Saved to nx.json so Nx won't ask again
  No, just this time       Skip prompts and run generators without AI validation
  No, never                Saved to nx.json so Nx won't ask again

如果您接受，代理会就地应用每个提示迁移并总结它所做的更改：

── Migration 2 of 2 · @aws/nx-plugin:update-custom-api-handlers ─────────
→ Running prompt with Claude Code…
✓ update-custom-api-handlers: Updated 3 API handlers to the new middleware signature.

如果您拒绝 — 或者没有安装代理，或者运行是非交互式的（例如 CI） — 提示迁移会被跳过并保存供您手动应用：

── Migration 2 of 2 · @aws/nx-plugin:update-custom-api-handlers ─────────
↷ Skipped — agentic flow disabled. Listed in next steps.


 NX   Successfully finished running migrations from 'migrations.json'.


1 migration applied, 0 commits created, 1 prompt migration skipped.


 NX   Some migrations have additional information, see below.


- Some prompt migrations were skipped. Review and apply each of the following
  prompt files to the workspace, in the listed order:
  - tools/ai-migrations/@aws/nx-plugin/2.0.0/prompt.md

每个跳过的提示都是 tools/ai-migrations/ 中的一个独立 markdown 指令文件 — 将其粘贴到您的编码代理中，或手动遵循其步骤。

最后，验证一切仍然构建成功，然后删除 migrations.json 并提交：

Terminal window
pnpm build

使用 AI 代理升级

Section titled “使用 AI 代理升级”

整个流程可以由 AI 编码代理端到端驱动 — 不会在交互式终端上阻塞。当 nx migrate --run-migrations 从代理内部运行时，Nx 会检测到这一点，跳过代理同意提示，并且不会生成嵌套代理，而是将每个提示迁移延迟回驱动运行的代理：

── Migration 2 of 2 · @aws/nx-plugin:update-custom-api-handlers ─────────
↷ Skipped — deferred to the AI agent driving this run. Listed in next steps.


 NX   Successfully finished running migrations from 'migrations.json'.


1 migration applied, 0 commits created, 1 prompt migration deferred.


 NX   Next steps for the AI agent driving this run


Apply the deferred prompts below, in order:
  1. tools/ai-migrations/@aws/nx-plugin/2.0.0/prompt.md
       (update-custom-api-handlers — prompt-only migration)
Then relay these migration-emitted notes to the user:
  - packages/website/vite.config.mts has a customised shape; add a coverage reporter manually.
Finally, summarize what was done across the run and commit the changes per workspace conventions.

执行升级的代理应该：

  1. 一次为一个包运行上述周期（nx migrate <package>@latest、安装、nx migrate --run-migrations），传递 --no-interactive 以抑制任何剩余的提示。
  2. 运行后，按列出的顺序读取 Next steps 下列出的每个延迟提示文件，并将其步骤直接应用到工作空间。
  3. 将任何迁移发出的注释（跳过的自定义文件、手动后续操作）转达给用户。
  4. 验证工作空间构建成功，然后删除 migrations.json 并提交，然后再开始下一个包的升级。