AI 驱动的 SPFx 1.22 升级：可复现的流程

Source: Dev.to

介绍

随着 SharePoint Framework (SPFx) 1.22 的发布，Microsoft 引入了全新的构建链。其变动之大，使得 SPFx 1.22 更像是一次 2.0 版本的发布，而非普通的次要更新。

传统的 gulp/webpack 工具链正逐步被 Microsoft 的新构建系统 Heft 所取代：

https://heft.rushstack.io

关键问题是：如何在不破坏任何功能的前提下，将已有的 SPFx 项目升级到 SPFx 1.22 和 Heft——尤其是当你第一次触碰一个旧项目时？

TL;DR

本文演示了一套可复现、由 AI 驱动的升级流程，帮助将 SPFx 项目迁移至 SPFx 1.22 与 Heft 构建链。文章末尾提供了一个可直接复制的 AI 提示，可在任何项目上运行。

免责声明 – 如果你使用 spfx‑fast‑serve，流程可能会有所不同；本文面向常规的 SPFx 项目。

我以前升级 SPFx 的方式

在撰写本文时，唯一受支持的版本是 1.22.0（候选发布版 0）。需要有人将代码更新到正式发布的版本。

自从我开始使用 Copilot 后，我直接将升级输出输入给它，Copilot 会为我完成升级。

一个提示完成升级

手动升级并不一定自动更好。人会犯错，可能会忽视重要细节。人工智能也会出错——但它往往能够自行发现并纠正这些问题（这确实有点吓人）。

为了解决升级，我创建了一个统一的提示，并在多个 SPFx 项目中进行测试，包括同一仓库中共存多个项目的情况。

下面我们逐步拆解。

1. 阅读指令

升级定义位于此处：

Follow these instructions to upgrade to the latest SPFx version using Heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain

通过把这段指令交给 AI，我明确告诉它我要做什么。我阅读升级定义，进行分析，并对所需步骤有了基本了解。

2. 构建安全网

使用 AI 时，我希望了解升级后可能面临的所有风险。仓库中常常隐藏着我未曾注意的文档。

Before you start the migration, perform a risk assessment of the
current solution and document it in a Markdown file.

这一步会为我提供项目的完整分析，突出潜在问题，并让我在造成任何损害之前中止升级。

示例风险评估输出

首先生成当前解决方案的清单，然后列出已识别的风险。

有了这些，我就能清晰地了解如何处理这些风险。

3. 接受后，请继续

在风险审查并被接受后，AI 将继续实际迁移工作。

Once those risks have been accepted, based on the current branch,
please create a new upgrade branch, follow the instructions, using
only the referenced versions, including optional steps that match my solution,
and normalize all npm scripts to follow best‑practice colon notation.

• 创建新分支 – 这可以保护主分支；如果升级失败，我只需删除升级分支。
• 逐步遵循官方指令 – AI 会判断针对特定解决方案哪些可选步骤是必需的。
• 规范化 npm 脚本 – 详细内容见下一节。

4. 遵循最佳实践 – 规范化 npm 脚本

文档推荐对 npm 脚本使用特定的命名约定。相关摘录如下：

{
  "scripts": {
    "test-only": "heft run --only test --",
    "deploy": "heft dev-deploy",
    "start": "heft start --clean",
    "build-watch": "heft build --lite",
    "package-solution": "heft package"
  }
}

提示中的语句

... normalize all npm scripts to follow best‑practice colon notation.

要求 AI 将使用连字符的脚本（例如 test-only）改为使用冒号的格式（例如 test:only）。这样可以让脚本更易阅读、分组以及调用（例如 npm run test:only）。

完整 AI 提示

复制下面的块并粘贴到你的 Copilot/ChatGPT 会话中，以在任何 SPFx 项目上运行相同的升级流程：

You are an expert SharePoint Framework developer. Follow these steps to upgrade a project to SPFx 1.22 using Heft:

1. Read the official migration guide:
   https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain

2. Perform a risk assessment of the current solution and write a detailed Markdown report that includes:
   - An inventory of the project’s dependencies, custom scripts, and configuration files.
   - Potential breaking changes (e.g., deprecated APIs, gulp tasks, custom webpack configs).
   - Any hidden documentation or scripts that could affect the upgrade.

3. Present the risk report to the user. Wait for the user to confirm that the risks are accepted.

4. Once accepted:
   - Create a new Git branch named `upgrade/spfx-1.22`.
   - Follow the migration guide step‑by‑step, using only the versions referenced in the guide.
   - For each optional step, decide whether it applies to the current project (based on the risk report) and include it if needed.
   - After the migration, update the `package.json` scripts:
     * Convert hyphenated script names to colon notation (e.g., `test-only` → `test:only`).
     * Ensure the scripts match the examples in the guide:
       - `"test:only": "heft run --only test --"`
       - `"deploy": "heft dev-deploy"`
       - `"start": "heft start --clean"`
       - `"build:watch": "heft build --lite"`
       - `"package:solution": "heft package"`

5. Run `npm install` and then `heft build` to verify the project builds successfully.

6. If any step fails, revert the changes on the upgrade branch, document the failure in the Markdown report, and stop.

Provide the final upgraded project structure, the updated `package.json`, and a short summary of what changed.

结论

通过将清晰的分步迁移指南与 AI 驱动的风险评估和脚本规范化相结合，您可以安全且可重复地将 SPFx 项目升级到 1.22 和 Heft。上面的单一提示封装了整个工作流，使得将相同的过程应用于任何代码库变得轻而易举。升级愉快！

脚本命名约定

{
  "scripts": {
    "package-solution": "heft package-solution",
    "deploy-azure-storage": "heft deploy-azure-storage",
    "eject-webpack": "heft eject-webpack",
    "trust-dev-cert": "heft trust-dev-cert",
    "untrust-dev-cert": "heft untrust-dev-cert"
  }
}

脚本名称中的短横线可以使用，但它们遵循一种不常见的模式，随着列表的增长会变得难以阅读。更常见（且通常是最佳实践）的方法是使用 冒号表示法，将相似的命令归为一组。

{
  "scripts": {
    "build": "heft build --clean",
    "build:watch": "heft build --lite",
    "build:prod": "heft build --production",

    "devcert:trust": "heft trust-dev-cert",
    "devcert:untrust": "heft untrust-dev-cert",

    "start": "npm run build:watch",

    "test": "heft test",
    "test:only": "heft run --only test --"

    // ...
  }
}

通过这种转换，能够更容易地将相关任务归为一组（例如，所有测试命令）。你还可以添加自定义命令——比如特殊的代码检查工具 (stylelint)——或 DevOps 任务。总体而言，脚本被更好地组织成 build、devcert、test、deploy 等分组。

手动更改升级期间

升级后需要进行一些手动调整，以重新组织脚本。

执行验收测试

在接受升级之前，运行最终的验收测试以确保一切正常。可能会出现多种问题：文档不完整、升级后隐藏的问题等。

As a final acceptance run, execute the build command to check for issues.
If issues are found, provide fact‑based solutions.

如果一切顺利，恭喜——您已经拥有升级后的解决方案。如果不成功，请迭代并修复问题。强调“基于事实”可以防止 AI 做出无依据的更改，并鼓励基于证据的修复。

文档

最后一步是为您所做的一切创建完整的文档。这可作为参考，并在出现意外情况时帮助排查问题。

提供已应用配置更改的详细摘要。

除了摘要外，建议根据升级过程中遇到的问题更新文档。

此外，请对 Microsoft 升级指南提出建议。

此步骤至关重要，因为它清晰地列出了出现的问题（如果有的话）以及已修复的内容。仅在您仅遇到 Microsoft 文档的轻微问题时才可选择性执行。

The Prompt

以下是用于将 SharePoint Framework (SPFx) 解决方案升级到 SPFx 1.22 的完整提示。无需工具或魔法——只需一个清晰的流程来描述所需的更新。

Follow these instructions to upgrade to the latest SPFx version using heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain

Before you start the migration, perform a risk assessment of the current solution and document it in a Markdown file.

Once those risks have been accepted, based on the current branch, please create a new upgrade branch, follow the instructions, using only the referenced versions, including optional steps that match my solution, and normalize all npm scripts to follow best‑practice colon notation.

As a final acceptance run, execute the build command to check for issues: when there are issues, please provide solutions based on facts.

Provide a detailed summary of the applied configuration changes.

In addition to the summary, recommend updates to the documentation based on issues encountered during the upgrade.

Also, make a recommendation for the Microsoft upgrade documentation.

升级过程

这些说明提供了一个可重复的升级计划，并已采取所有预防措施。作者建议在升级时使用 Claude Sonnet 4，因为它比 Copilot 能产生更可靠的结果。

整体升级遵循 15 步计划，并允许用户交互。运行时间通常为几分钟。

在升级过程中，手动修复了一个 Microsoft 未文档化的 ESLint 配置问题，方法是对比 SPFx package.json 中的依赖项。作者使用了最小化的 ESLint 配置；若需完整的 Microsoft ESLint 文件，请从其他模板中复制。

判决

总体而言，使用 AI 的 SPFx 1.22 升级过程几乎完美无缺。唯一真正遇到的问题是微软官方升级指南中有一个小的文档缺口。基于提示的方式已在 Claude Sonnet 上成功测试。

4（通过 GitHub Copilot）— 跨多个项目和 SPFx 解决方案

对我而言，这个 AI 辅助的升级流程绝对值得使用。与其花费数小时手动升级 SharePoint Framework，不如在几分钟内完成整个使用 Heft 的 SPFx 迁移。

由于工作流内置了安全网，我可以随时决定保留或丢弃升级分支，而不会危及主代码库。

我最欣赏的是此方法可复现，并对每个 SPFx 项目应用相同的自动升级过程。一旦所有内容得到妥善记录，使用 Heft 升级到 SPFx 1.22 几乎是毫不犹豫的决定。