meteor-modern-build-stack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Modern build stack

现代构建栈

The modern build stack is two independent tracks. Enable either or both.

Meteor Bundler Optimizations (Meteor 3.3+). One flag, SWC replaces Babel, SWC minifier replaces Terser,
```
@parcel/watcher
```
replaces the legacy watcher, development skips legacy archs.
Rspack Bundler Integration (Meteor 3.4+). Atmosphere package delegates app-code compilation to Rspack. Tree shaking, ESM, code splitting via HTTP, modern bundler plugins.

Standard current

meteor create

application skeletons ship both enabled. Purposefully small or compatibility-oriented skeletons, including

minimal

and

legacy

, may omit Rspack or the modern flag. Inspect the generated

package.json

and

.meteor/packages

instead of inferring features only from the Meteor version. For existing apps, enable optimizations first, then add Rspack once the app code is standards-clean.

现代构建栈包含两条独立的路径，可启用其中一条或同时启用两条。

Meteor打包器优化（Meteor 3.3及以上版本）：只需一个配置项，SWC将替代Babel，SWC压缩器替代Terser，
```
@parcel/watcher
```
替代旧版监视器，开发环境将跳过旧版架构。
Rspack打包器集成（Meteor 3.4及以上版本）：通过Atmosphere包将应用代码编译委托给Rspack，支持摇树优化、ESM、基于HTTP的代码分割以及现代打包器插件。

当前标准的

meteor create

应用骨架默认同时启用这两项功能。专为小型项目或兼容性设计的骨架（包括

minimal

和

legacy

）可能会省略Rspack或现代配置项。请查看生成的

package.json

和

.meteor/packages

文件，而不要仅根据Meteor版本推断功能。对于现有应用，请先启用优化功能，待应用代码符合标准规范后再添加Rspack。

Enable Meteor Bundler Optimizations

启用Meteor打包器优化

Add to

package.json

json

"meteor": {
  "modern": true
}

This enables SWC, the SWC minifier, the modern watcher, and dev-mode web arch skipping. Each falls back to legacy when something is incompatible, so this is backward compatible.

Opt out of pieces:

json

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

Or scope SWC:

transpiler.excludeApp

transpiler.excludeNodeModules

transpiler.excludePackages

transpiler.excludeLegacy

. Accept

true

or an array of paths/regexes.

Verbose transpiler logs to diagnose Babel fallbacks:

json

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

Look for

[Transpiler] Used Babel for <file> Fallback

. The common cause is nested imports; see

references/meteor-bundler-optimizations.md

在

package.json

中添加以下配置：

json

"meteor": {
  "modern": true
}

此配置将启用SWC、SWC压缩器、现代监视器以及开发模式下的web架构跳过功能。当出现不兼容情况时，各项功能会自动回退到旧版实现，因此该配置具备向后兼容性。

可选择性关闭部分功能：

json

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

也可对SWC进行范围限制：

transpiler.excludeApp

、

transpiler.excludeNodeModules

、

transpiler.excludePackages

、

transpiler.excludeLegacy

，支持设置为

true

或路径/正则表达式数组。

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

json

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

查找

[Transpiler] Used Babel for <file> Fallback

日志信息。常见原因是嵌套导入，详情请查看

references/meteor-bundler-optimizations.md

。

Enable Rspack integration

启用Rspack集成

bash

meteor add rspack

On first run the package installs the project-level Rspack setup. App code moves to Rspack; Meteor still handles Atmosphere packages and produces the final bundle. Requires entry points in

package.json

and no nested imports in app code. To migrate an existing app, use the

migrate-to-rspack

skill.

rspack

and

@meteorjs/rspack

follow the Meteor release, not the

@rspack/core

@rspack/cli

major. Meteor 3.4.0 uses both integration packages at v1. Meteor 3.4.1 and 3.5 use

rspack@1.1.0

with

@meteorjs/rspack@2.0.1

; Meteor 3.5.1 uses

rspack@1.2.0

with

@meteorjs/rspack@2.1.0

. Inspect

.meteor/versions

package.json

, and the lockfile. Run

meteor update --npm

after changing the Meteor release.

bash

meteor add rspack

首次运行时，该包会安装项目级别的Rspack配置。应用代码将交由Rspack处理，Meteor仍负责管理Atmosphere包并生成最终打包文件。要求

package.json

中存在入口点，且应用代码中无嵌套导入。如需迁移现有应用，请使用

migrate-to-rspack

技能。

rspack

和

@meteorjs/rspack

的版本与Meteor版本同步，而非跟随

@rspack/core

或

@rspack/cli

的大版本。Meteor 3.4.0使用这两个集成包的v1版本；Meteor 3.4.1和3.5使用

rspack@1.1.0

与

@meteorjs/rspack@2.0.1

；Meteor 3.5.1使用

rspack@1.2.0

与

@meteorjs/rspack@2.1.0

。请查看

.meteor/versions

、

package.json

和锁文件。更改Meteor版本后，请运行

meteor update --npm

。

SWC config files

SWC配置文件

text

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

Only the first found is used. Use

.swcrc

for static config,

swc.config.js

for environment-driven config. The file name must be exactly

.swcrc

, not

config.swcrc

Install

@swc/helpers

to externalize SWC helpers (smaller bundles):

bash

meteor npm install --save @swc/helpers

New apps ship with this preinstalled. Normally no further setup is needed; Meteor's pipeline detects it and emits imports instead of inlining. If only a production or legacy bundle fails on a helper import, inspect Rspack-generated and final Meteor output before changing

.swcrc

or adding manual imports.

text

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

仅会使用第一个找到的配置文件。使用

.swcrc

用于静态配置，

swc.config.js

用于基于环境的动态配置。文件名必须严格为

.swcrc

，不能是

config.swcrc

。

安装

@swc/helpers

以外部化SWC辅助函数（减小打包体积）：

bash

meteor npm install --save @swc/helpers

新创建的应用默认已预安装该包。通常无需进一步配置，Meteor的流水线会自动检测并生成导入语句而非内联代码。若仅生产环境或旧版打包文件出现辅助函数导入失败，请先检查Rspack生成的文件和Meteor最终输出，再修改

.swcrc

或添加手动导入。

Rspack config files

Rspack配置文件

text

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

Use

defineConfig

from

@meteorjs/rspack

. The function receives a

Meteor

parameter with build flags and helpers. See

references/rspack-config.md

for the full table and the most useful helpers (

extendSwcConfig

compileWithRspack

compileWithMeteor

extendConfig

splitVendorChunk

persistDevFiles

disablePlugins

enablePortableBuild

setCache

text

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

Skip directories the bundler does not need to watch. Same syntax as

.gitignore

. Place at any depth; rules apply to the subtree.

gitignore

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

For per-command rules, set the

METEOR_IGNORE

env var.

Do not copy

.gitignore

into

.meteorignore

blindly. Exclude unrelated large trees that Meteor does not need, but never match the active Rspack build context: Meteor consumes its generated main and test modules during final assembly.

Rspack also generates

_build/

public/build-assets/

public/build-chunks/

, and

private/build-assets/

. Add those paths to the native ignore configuration of recursive formatters, linters, typecheckers, test discovery, coverage, and IDEs.

.gitignore

alone is insufficient.

忽略打包器无需监视的目录，语法与

.gitignore

相同。可放置在任意目录层级，规则仅适用于当前子树。

gitignore

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

如需为特定命令设置规则，请使用

METEOR_IGNORE

环境变量。

请勿盲目将

.gitignore

复制到

.meteorignore

。忽略Meteor不需要的无关大型目录，但绝不能匹配Rspack的活动构建上下文：Meteor在最终组装过程中需要读取其生成的主模块和测试模块。

Rspack还会生成

_build/

、

public/build-assets/

、

public/build-chunks/

和

private/build-assets/

目录。请将这些路径添加到递归格式化工具、代码检查工具、类型检查工具、测试发现工具、覆盖率工具和IDE的原生忽略配置中，仅靠

.gitignore

是不够的。

Minifier ownership

压缩器归属

"modern": true

selects Meteor's modern standard minifier. A third-party Atmosphere package that provides the JavaScript minifier remains part of the final Meteor assembly even when Rspack compiles app modules. Inventory custom minifier packages before migration. Keep or remove one only after comparing production output, source maps, build time, and runtime behavior.

"modern": true

会选择Meteor的现代标准压缩器。即使Rspack编译应用模块，提供JavaScript压缩器的第三方Atmosphere包仍会参与Meteor的最终组装过程。迁移前请梳理自定义压缩器包，仅在对比生产输出、源映射、构建时间和运行时行为后，再决定保留或移除某个包。

Production legacy builds

生产环境旧版构建

Dev skips

web.browser.legacy

and

web.cordova

with

"modern": true

. Production still ships legacy by default. To drop legacy in production too, add

modern

.meteor/platforms

text

server
browser
modern

启用

"modern": true

后，开发环境会跳过

web.browser.legacy

和

web.cordova

。生产环境默认仍会打包旧版架构。若要在生产环境中也移除旧版架构，请将

modern

添加到

.meteor/platforms

：

text

server
browser
modern

Memory limits

内存限制

Rspack runs as a child process and may OOM on large apps. Raise the heap for tool processes temporarily when capturing evidence (Meteor 3.4.1+):

bash

TOOL_NODE_FLAGS="--max-old-space-size=16384" meteor run

On Meteor 3.4.0, use

NODE_OPTIONS="--max-old-space-size=16384"

First distinguish a one-shot build failure from growth during a long watch session. Audit large directories visible to Meteor and check the exact release for fixes. Test heap size and persistent cache as separate variables; revert a change that does not improve the failure or a measured memory trend.

Rspack作为子进程运行，大型应用可能会出现内存不足（OOM）的情况。在捕获问题证据时，可临时提高工具进程的堆内存（Meteor 3.4.1及以上版本）：

bash

TOOL_NODE_FLAGS="--max-old-space-size=16384" meteor run

对于Meteor 3.4.0版本，请使用

NODE_OPTIONS="--max-old-space-size=16384"

。

首先区分是一次性构建失败还是长时间监视会话中的内存增长。检查Meteor可见的大型目录，并查看具体版本的修复情况。分别测试堆内存大小和持久化缓存的影响；若某项更改未能改善故障或内存趋势，请回退该更改。

Multiple instances

多实例运行

METEOR_LOCAL_DIR

isolates

_build

build-assets

build-chunks

bash

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

使用

METEOR_LOCAL_DIR

隔离

_build

、

build-assets

、

build-chunks

bash

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

Anti-patterns

反模式

Enable optimizations and Rspack at the same time on a legacy app. Enable
```
"modern": true
```
first, clean up Babel fallbacks, then add Rspack.

Edit files inside

_build/

public/build-assets/

public/build-chunks/

, or

private/build-assets/

. Autogenerated.

Assume
```
.gitignore
```
prevents code-quality tools from scanning generated Rspack output. Configure each tool's own ignore mechanism.
Copy
```
.gitignore
```
to
```
.meteorignore
```
. Git may ignore Rspack's generated handoff even though Meteor must read it.
Remove a custom Atmosphere minifier only because Rspack is enabled. Benchmark the final production bundle first.
Disable Rspack persistent cache without need. It is the default and the main rebuild-speed win. Disable only when investigating OOM or a cache-related Rspack bug.
Name an SWC config
```
config.swcrc
```
or
```
rc.swc
```
. Only
```
.swcrc
```
is read.

在旧版应用上同时启用优化和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 bug时才禁用。
将SWC配置文件命名为
```
config.swcrc
```
或
```
rc.swc
```
：只有
```
.swcrc
```
会被读取。

另请参阅

references/meteor-bundler-optimizations.md

```
references/rspack-config.md
```
```
references/eval-cases.md
```
For converting an existing app to Rspack:
```
migrate-to-rspack
```
skill.

references/meteor-bundler-optimizations.md

```
references/rspack-config.md
```
```
references/eval-cases.md
```
如需将现有应用转换为兼容Rspack的版本：使用
```
migrate-to-rspack
```
技能。

meteor-modern-build-stack

Original

Translation

Modern build stack

现代构建栈

Enable Meteor Bundler Optimizations

启用Meteor打包器优化

Enable Rspack integration

启用Rspack集成

SWC config files

SWC配置文件

Rspack config files

Rspack配置文件

.meteorignore

.meteorignore

Minifier ownership

压缩器归属

Production legacy builds

生产环境旧版构建

Memory limits

内存限制

Multiple instances

多实例运行

Anti-patterns

反模式

See also

另请参阅