升级到 v3
自 v3 开始，现在可以通过将 @salesforce/retail-react-app 更新添加为 npm 依赖项并在项目中启用 模板扩展性 来使用更新。
本指南介绍如何将 PWA Kit 项目从 v2.7.x 更新到 v3.0.0。
我们为 PWA Kit v3 添加了许多新功能，包括：
🔨 模板可扩展性：显著减少项目的代码占用量，并减少开发工作、拥有成本和未来升级的麻烦。有关更多详细信息，请参阅模板可扩展性指南！
🪝 @salesforce/commerce-sdk-react "hooks" integration:将 API 调用与项目实施解耦，允许 API 调用作为 npm 库依赖项进行升级，并通过 TanStack 查询 带来许多出色功能（包括状态管理等）。请参阅 Commerce SDK React docs 文档以开始使用！
⚛️ 主要供应商库更新，包括支持 React 18、Node 16 / 18、Chakra 2 等等。
从 v2.7.x 迁移到 v3.x 时要做的首要决定之一是是否要利用模板扩展性。为了从中受益，您必须从 @salesforcef/retail-react-app（或另一个可扩展应用程序）导入至少一个文件。您可以选择要从基本模板继承多少个文件，但必须承诺至少导入一个。
从那里，考虑您从通过 npx pwa-kit-create-app@2.x 生成的原始项目中修改了多少文件。一些客户拥有大量（可能数百个）文件，但即便如此，仍有大量文件无法修改。这些未修改的文件是从 @salesforce/retail-react-app 导入的良好候选文件，但我们建议仔细、逐步执行此过程。@salesforce/retail-react-app 中的很多文件都相似，但已较 v2.x 版 PWA Kit Retail React App 之前的状态发生了变化。特别是，@salesforce/commerce-sdk-react 集成（稍后将更详细地介绍迁移细节）导致大量文件在导入和文件结构方面发生变化。整个 commerce-api 目录已从 Retail React App 中删除。
当迁移项目以使用模板扩展性时，请注意，2.x 版本的 PWA Kit SDK 和通过 npx pwa-kit-create-app@2.x 生成的项目不具有 @salesforce/commerce-sdk-react 依赖关系，而较新的代码 @salesforce/retail-react-app@^1.x 大量使用此库，这会触及和更改许多文件。要了解更改的幅度，您可以比较此 Github diff https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket 中的 release-2.7.x → release-3.0.x 并搜索 @salesforce/commerce-sdk-react，然后记下添加此导入的所有添加内容。
如果您的应用程序尝试与版本 2.x （包括 app/commerce-api 目录）共享代码，您可能会面临向捆绑包中添加非必要代码的风险，其中该代码同时存在于 commerce-api 文件夹和 @salesforce/commerce-sdk-react npm 模块中（以两种完全不同的形式）。
自 v3.0.0 开始，PWA Kit 使用不同的获取策略 withReactQuery。该策略利用 react-query 库并在 SSR 渲染过程中启用查询。@salesforce/retail-react-app 使用由 react-query 支持的 @salesforce/commerce-sdk-react。
为了使挂钩在服务器端工作，您需要用新的高阶组件 AppConfig 包装您的 withReactQuery 组件。
对于那些尝试升级到 v3 并继续使用 getProps 的项目，请使用 withLegacyGetProps 组件包装您的 AppConfig 组件。
您可以同时使用 withReactQuery 和 withLegacyGetProps。
更改 package.json 中的依赖项，如下所示
更新 package.json 中的引擎以支持 Node 18 和 npm 9。在 package.json 中从 peerDependencies 移除 @chakra-ui/system，因为版本 2 是 Chakra 的最新主要版本。
存在错误 nswapi，它是与 Chakra 2 不兼容的 jest-environment-jsdom 的依赖项。在使用 Modal 组件的某些测试中，它会发出错误“'2.2.2 版的 nwsapi 包，并删除 npm 7 支持。
在 package.json 中添加 overrides 属性以强制执行功能包版本：
使用 npm i 重新安装项目的依赖项。
对于 react-hook-form 迁移，请阅读此处 的 react-hook-form 官方文档。在 PWA 项目中，有两个地方需要改动：
-
当
errors对象已被移动到formState对象中时，将表格errors对象移动到app/components/forms/*挂钩的另一层破坏中。 -
将
Controller中的渲染道具移入field道具中。Render的回调签名返回包含field和fieldState的对象。
自 React 18 开始，水合警告显示为错误，而不是像 React 17 中那样显示为警告。需要更新一些代码来抑制这些潜在错误，这些错误会在出现水合错误时阻止应用程序构建。修复这些错误以确保应用程序能够同构渲染至关重要。发生此错误的原因是服务器或客户端之间不匹配。如果组件或页面碰巧有条件渲染，则必须确保在渲染任何特定于客户端的代码之前完成水合作用。
在您的项目中，创建一个实用函数来确定水合是否已完成。您可以使用 window.__HYDRATING__ 在 pwa-kit-react-sdk 中提供的内置变量。
只要使用条件渲染，就添加此函数。PWA Kit 项目中有几个地方可以添加该功能：
请参阅此处。
如果您安装的浏览器插件会干扰 DOM 渲染，则可能会在页脚中出现水合错误。例如，如果您使用 LastPass 扩展，您可以在页脚中看到 Subscribe 组件上的错误，因为 LastPass 接管浏览器的渲染以注入图标,从而启用字段内弹出窗口。如果这种接管发生在水合过程中，则会出现错误。不必使用 isHydrated() 的一个简单技巧是切换输入组件的顺序，如下所示：
如果您的项目使用 @chakra-ui/react 库中与 Retail React App 模板不同的组件和 API，请查看官方 Chakra 2 迁移文件。
为了支持 Chakra 2，有一些文件需要为基于 Retail React App 模板的项目进行更新：
在 Accordion 组件中删除 allowToggle，因为 allowMultiple 和 allowToggle 不能在 Chakra 2 中同时使用。
在 Footer 组件中，已废弃从 @chakra-ui/react 直接导入 StylesProvider。您必须通过 createStylesContext('Footer') 创建它。
在调用任何操作之前设置 userEvent，并在使用 userEvent 的单元测试中等待该操作，因为在 React 测试库 v14.0.0 中，所有用户操作都是异步的，并且需要在执行用户操作之前调用 setup。
例如：
有关更多详细信息，请参阅测试库的 userEvent 的官方文档。
或者，为了避免在许多单元测试中重复调用 setup()，您可以在渲染测试组件之前通过 app/utils/test-util.js 设置您的 userEvent，并将其与渲染结果一起返回，以便测试可以执行用户操作，而无需调用 setup()。
在 jest-setup 中，有一个模拟依赖项可能会引发关于 TextDecoder 在 jest-setup.js 中未定义的错误。将以下内容添加到 jest-setup.js：
从 2.0 版 PWA Kit SDK 或通过 npx pwa-kit-create-app@2.x 生成的项目进行迁移时，@salesforce/commerce-sdk-react 代码已经过重大重构，以删除 app/commerce-api/* 目录。而不是那些处理 API 请求并充当 SDK 的文件 @salesforce/commerce-sdk-react 取代了该功能。v3 版 SDK 与第一版 @salesforce/retail-react-app@^1.x 相关，因为 SDK 大量使用此库。
@salesforce/commerce-sdk-react 的执行改变了 Retail React App 中的许多文件。要了解变化的幅度，请比较此 GitHub diff中的release-2.7.x → release-3.0.x并搜索 @salesforce/commerce-sdk-react。在 diff 中，记下添加此导入的所有添加内容。