migrate-to-rspack

将现有应用迁移到 Rspack

Rspack 编译应用代码；Meteor 构建 Atmosphere 包并组装 bundle。保留这些包，但审查其架构和浏览器依赖。

需要 Meteor 3.4+。建议启用 "meteor": { "modern": true }，并先修复 Babel 回退方案。如需设置/辅助工具，请使用 meteor-modern-build-stack。

将 @meteorjs/rspack 与 Meteor 版本匹配，而不是与 @rspack/core 或 @rspack/cli 匹配：

Meteor	rspack	@meteorjs/rspack	能力边界
3.4	1.0.0	1.0.0	基础集成和辅助工具。
3.4.1 和 3.5	1.1.0	2.0.1	新增 v2 辅助工具和继承的 TOOL_NODE_FLAGS。
3.5.1	1.2.0	2.1.0	修订客户端 polyfill 和扩展发现机制。
3.5.2	1.3.0	2.2.0	依赖诊断、模式隔离、完整应用/TLA 和缓存修复。
3.6-beta.0	1.4.0-beta360.0	3.0.0-beta.1	Rspack 2.2.0 和支持工作区的安装。
3.6-beta.1	1.4.0-beta360.1	3.0.0-beta.2	TypeScript 重建循环修复；Node 26.8.2。
3.6-beta.3	1.4.0-beta360.3	3.0.0-beta.3	Rspack 2.2.7；架构图和测试忽略修复。
3.6-rc.0	1.4.0-rc360.0	3.0.0-rc.0	Rspack 2 和独立的架构入口。

检查 .meteor/versions、package.json 和锁文件：Atmosphere、Meteor npm 集成和 Rspack 核心版本彼此独立。启用自动安装后，启动时会对齐依赖；请检查并提交这些更改。也可以使用 meteor update --npm。保持版本配对。

已经在使用 Rspack？升级到 Meteor 3.6 beta 或 RC 时，请遵循 Rspack 1 到 2 及其工具链检查。保留有效的条目/配置；跳过下方的首次激活步骤。

决策流程

1. 应用是否在 package.json 的 meteor.mainModule 中定义了客户端和服务器入口？如果没有，请定义。此项为必需。
2. 跟踪客户端和客户端测试依赖图。它们是否会到达 CommonJS 导出赋值、Node 内置模块、仅限服务器的本地包入口，或干净检出中缺失的生成输入？如果会，请先修复边界，再激活。参见 references/client-graph-preflight.md。
3. 应用代码中是否包含嵌套导入（位于 if、函数或其他代码块内的 ES import）？如果有，请将其移至顶层，或转换为动态 import() / require。应用代码必须遵循此要求；Atmosphere 包中可以使用。
4. 应用是否依赖 Meteor 构建插件（less、fourseven:scss、 coffeescript、zodern:melte、jorgenvatle:vite）？请规划 Rspack loader 替代方案，并在移除前证明能力等效。参见 references/framework-and-css.md。
5. 应用是否依赖从 CommonJS 包进行裸默认导入 （import x from "some-cjs"）？请决定是改写为 import * as x，还是在 .swcrc 中恢复 Meteor 风格的互操作。参见 references/code-migrations.md。
6. 应用是否仅用于服务器？只设置 mainModule.server。Rspack 仍会 打包服务器；客户端会跳过。
7. 应用是否将 CSS 或 HTML 放在入口文件夹之外，或导入应用本地 符号链接？请使用 meteor.modules 或 resolve.symlinks: false 保留边界；参见相关文档。
8. 运行 meteor add rspack，并查看详细的 [Transpiler] 日志，确认是否 仍有 (app) 失败项。

必需：入口

{
  "meteor": {
    "mainModule": {
      "client": "client/main.js",
      "server": "server/main.js"
    },
    "testModule": "tests.js"
  }
}

如果没有 mainModule，Rspack 就没有入口。Meteor 的急切加载模式 不适用：Rspack 不会自动发现模块。有关 CSS 和 HTML 路由，请参见 references/framework-and-css.md。

有关 3.6-beta.3 和 RC 的独立 legacy/native 入口以及早期版本限制，请阅读保留架构。

必需：应用代码中不得有嵌套导入

对应用代码应用嵌套导入改写。 使用返回 Promise 的 import() 时，请调整调用方； Atmosphere 包代码仍由 Meteor 的打包器处理。

必需：预留构建目录

此集成会写入 _build/、public/build-assets/、 public/build-chunks/、private/build-assets/。这些目录会自动添加到 .gitignore。 如果项目已使用其中任何名称，请在 package.json 中重命名：

{
  "meteor": {
    "buildContext": "build",
    "assetsContext": "assets",
    "chunksContext": "chunks"
  }
}

不要编辑这些目录下的任何文件。请将它们排除在 IDE 索引，以及所有递归格式化、lint、类型检查、测试发现和覆盖率扫描之外。.gitignore 不会配置这些工具。

不要在 .meteorignore 或 METEOR_IGNORE 中匹配当前活动的构建上下文。Rspack 会在其中写入面向 Meteor 的入口模块，然后由 Meteor 读取这些模块来组装最终 bundle。审查忽略规则前，先处理已重命名的上下文。

替换构建插件

大多数应用文件构建插件都可以迁移到 Rspack loader。移除插件前，请证明功能对等；将冲突插件的启用与移除作为一个可逆更改。参见 references/framework-and-css.md。

旧插件	替代方案
meteor/less	less-loader。参见 references/framework-and-css.md。
fourseven:scss	sass-loader + sass-embedded。参见参考文档。脚手架见 meteor create --full。
meteor/coffeescript	coffee-loader（可选择与 swc-loader 链接）。
zodern:melte（Svelte）	官方 Rspack Svelte loader。
jorgenvatle:vite（Vue/Solid）	原生 Rspack Vue/Solid loader。
babel-plugin-react-compiler	在 3.6 beta 配套方案中使用 SWC；更早的集成保留 Babel。参见框架参考文档。
zodern:types	bundler 迁移期间保留可正常工作的声明提供器；beta.1 原生采用是另一项明确的选择。

仅处理 Atmosphere 包文件的插件可以保留。处理应用文件夹文件（入口文件夹除外）的插件必须迁移到 Rspack。

CommonJS 默认导入互操作

优先使用命名空间导入。有关互操作覆盖及其对整个应用的 CommonJS/tree-shaking 影响，请阅读 references/code-migrations.md。

CI 和 Docker

在本地处理所需的 npm 更新，并提交 package.json 和锁文件。使用现有包管理器执行冻结安装（包含开发依赖），然后构建。 在 [email protected]（Meteor 3.5.2）上，meteor.autoInstallDeps: false 仍会报告缺失或过时的依赖项以及手动命令；更早版本的选择退出行为可能会跳过这些检查。检查首个依赖项/配置错误和实际项目根目录，再决定如何修复。参见 references/troubleshooting.md。

反模式

• 先添加 Rspack，再修复 Babel 回退。使用 "meteor": { "modern": { "transpiler": { "verbose": true } } } 找出它们，并在仍使用仅优化的技术栈时修复。
• 在 .swcrc 中全局恢复 CJS 互操作，以避免迁移少数导入。这会用真正的 bundle 体积收益换取短期便利。
• 提交 _build/、public/build-assets/、public/build-chunks/、 private/build-assets/。这些目录会自动生成。
• 更改发行版本，却不检查与之配套的依赖项，也不提交权威锁文件。请验证干净安装和生产构建。

另请参阅

• references/eval-cases.md
• 有关设置、辅助工具和 rspack.config.js API：meteor-modern-build-stack。