meteor-modern-build-stack

现代构建技术栈

现代构建技术栈包含两条独立路线，可启用其中一条或两条。

1. Meteor Bundler 优化（Meteor 3.3+）。只需一个标志，SWC 替代 Babel，SWC 压缩器替代 Terser，@parcel/watcher 替代 旧版文件监视器，开发环境跳过旧版架构。
2. Rspack 打包器集成（Meteor 3.4+）。Atmosphere 包 将应用代码编译委托给 Rspack。支持摇树优化、ESM、通过 HTTP 实现代码 分割以及现代打包器插件。

当前的 meteor create 应用骨架默认启用这两项功能。有意保持精简或注重兼容性的骨架（包括 minimal 和 legacy）可能不会启用 Rspack 或现代标志。请检查生成的 package.json 和 .meteor/packages，不要仅根据 Meteor 版本推断功能。对于现有应用，请先启用优化，再在应用代码符合标准后添加 Rspack。

启用 Meteor Bundler 优化

添加到 package.json：

"meteor": {
  "modern": true
}

这会启用 SWC、SWC 压缩器、现代文件监视器，以及开发模式下跳过 Web 架构。遇到不兼容情况时，每项功能都会回退到旧版实现，因此向后兼容。

选择退出部分功能：

"meteor": {
  "modern": {
    "transpiler": false,
    "minifier": false,
    "watcher": false,
    "webArchOnly": false
  }
}

或者限定 SWC 的作用范围：transpiler.excludeApp、transpiler.excludeNodeModules、 transpiler.excludePackages、transpiler.excludeLegacy。可接受 true 或 路径／正则表达式数组。

启用详细转译器日志，以诊断回退到 Babel 的情况：

"meteor": {
  "modern": {
    "transpiler": { "verbose": true }
  }
}

查找 [Transpiler] Used Babel for <file> Fallback。常见原因是嵌套导入；请参阅 references/meteor-bundler-optimizations.md。

启用 Rspack 集成

meteor add rspack

首次运行时，该包会安装项目级 Rspack 设置。应用代码将交由 Rspack 处理；Meteor 仍负责处理 Atmosphere 包并生成最终构建包。要求在 package.json 中声明入口点，且应用代码中没有嵌套导入。迁移现有应用，请使用 migrate-to-rspack 技能。

检查 .meteor/versions、package.json 和锁文件。RC 版本组合为 [email protected] 和 @meteorjs/[email protected]，核心／CLI 版本为 2.2.7。 请参阅发行版组合 和依赖项最低版本。 Rspack 会转译 TypeScript。请使用 meteor-typescript 处理声明和类型检查；参阅 类型检查器边界。

脚手架、PWA 和离线行为

如需了解新应用骨架选择，或与框架无关的 PWA／Workbox 设置，请参阅 脚手架和 Service Worker。 Meteor 3.6（已在 3.6-beta.0 上验证）新增独立的 --pnpm 工作区和 --pwa Blaze 启动模板；两者都不会转换现有应用。Worker 会缓存 应用外壳／资源，不会缓存离线 Meteor 数据。现有打包器迁移仍由 migrate-to-rspack 负责。

SWC 配置文件

.swcrc > swc.config.js > swc.config.ts

只会使用找到的第一个配置文件。静态配置使用 .swcrc，由环境驱动的配置使用 swc.config.js。文件名必须严格为 .swcrc，不能是 config.swcrc。

安装 @swc/helpers，将 SWC 辅助函数外置（减小构建包体积）：

meteor npm install --save @swc/helpers

新应用已预装此依赖。通常无需进一步设置；Meteor 的处理流水线会检测到它，并生成导入语句而不是内联代码。如果只有生产或旧版构建包在导入辅助函数时失败，请先检查 Rspack 生成的输出和最终 Meteor 输出，再修改 .swcrc 或添加手动导入。

对于已解析的 SWC 载体，ERR_SWC_NATIVE_CACHE 需要在可执行文件系统上设置绝对路径的、由当前用户拥有的 SWC_NATIVE_BINDING_CACHE。清理构建缓存无法修复此问题；请参阅 meteor-debugging。

Rspack 配置文件

rspack.config.js | rspack.config.ts | rspack.config.mjs | rspack.config.cjs

请使用 @meteorjs/rspack 中的 defineConfig。此函数接收一个 Meteor 参数，其中包含构建标志和辅助函数。完整表格以及最实用的辅助函数（extendSwcConfig、compileWithRspack、compileWithMeteor、extendConfig、splitVendorChunk、persistDevFiles、disablePlugins、enablePortableBuild、setCache）请参阅 references/rspack-config.md。

.meteorignore

跳过打包器无需监视的目录。语法与 .gitignore 相同。可放在任意深度；规则适用于整个子树。

docs/
design/
cypress/
scripts/
*.md
!README.md

对于单条命令的规则，设置 METEOR_IGNORE 环境变量。

对于 3.6-beta.3 配对，请阅读测试忽略边界， 了解有序的用户例外、纳入的父目录和单独生成的规则。

不要盲目地将 .gitignore 复制到 .meteorignore。排除 Meteor 不需要的无关大型目录树，但绝不要匹配当前活跃的 Rspack 构建上下文：Meteor 会在最终组装期间使用生成的主模块和测试模块。

Rspack 还会生成 _build/、public/build-assets/、 public/build-chunks/ 和 private/build-assets/。在 Meteor 3.5.2 上，还要包含当前活跃的带后缀变体，例如 build-assets-test 和 build-chunks-app-test，以及自定义上下文名称。将这些路径添加到递归格式化工具、代码检查工具、类型检查工具、测试发现工具、覆盖率工具和 IDE 的原生忽略配置中。仅使用 .gitignore 不够。

压缩器归属

"modern": true 会选择 Meteor 的现代标准压缩器。即使 Rspack 编译应用模块，提供 JavaScript 压缩器的第三方 Atmosphere 包仍属于最终 Meteor 组装的一部分。迁移前请盘点自定义压缩器包。只有比较生产环境输出、源映射、构建时间和运行时行为后，才决定保留或移除某个包。

生产环境旧版构建

对于 3.6-beta.3 或 3.6-rc.0 上单独的 mainModule.legacy 或精确架构条目， 请阅读架构入口点。 较早的集成仍保留共享客户端行为。

在开发环境中，使用 "modern": true 会跳过 web.browser.legacy 和 web.cordova。 默认情况下，生产环境仍会打包旧版构建。若要在生产环境中也移除旧版构建， 请将 modern 添加到 .meteor/platforms：

server
browser
modern

内存限制

若工具进程发生 OOM 或监视内存持续增长，请使用特定版本的 堆和缓存检查。

多个实例

Meteor 3.5.2 会在同一个上下文中分别生成开发环境、普通测试和完整应用测试的输出（_build/main-dev、_build/test、_build/app-test，以及 带模式后缀的资源/分块）。这不会隔离 Meteor 缓存、本地 Mongo 或端口。若要使用单独的本地状态或运行两个相同模式的实例，请使用 不同的端口和 METEOR_LOCAL_DIR 值；较早的集成也需要这样做，以隔离不同模式的输出：

PORT=3000 METEOR_LOCAL_DIR=.meteor/local-1 meteor run
PORT=3001 METEOR_LOCAL_DIR=.meteor/local-2 meteor run

反模式

• 在旧版应用中同时启用优化和 Rspack。先启用 "modern": true，清理 Babel 回退配置，然后再添加 Rspack。
• 编辑 _build/、public/build-assets/、 public/build-chunks/ 或 private/build-assets/ 中的文件。这些文件由工具自动生成。
• 认为 .gitignore 能阻止代码质量工具扫描生成的 Rspack 输出。请配置每个工具自身的忽略机制。
• 将 .gitignore 复制到 .meteorignore。Git 可能会忽略 Rspack 生成的 交接文件，但 Meteor 必须读取这些文件。
• 仅因启用了 Rspack 就移除自定义 Atmosphere 压缩器。 请先对最终生产环境打包结果进行基准测试。
• 无故禁用 Rspack 持久化缓存。它是默认设置，也是提升重建速度的主要因素。仅在调查 OOM 或缓存相关的 Rspack 错误时才禁用。
• 将 SWC 配置命名为 config.swcrc 或 rc.swc。只有 .swcrc 会被读取。

另请参阅

• references/meteor-bundler-optimizations.md
• references/rspack-config.md
• references/eval-cases.md
• 将现有应用转换为 Rspack：migrate-to-rspack 技能。