migrate-to-meteor-3

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate a Meteor 2.x application to Meteor 3.x

将Meteor 2.x应用迁移至Meteor 3.x

Meteor 3 removed Fibers. Server-side Mongo APIs are async. The module system enforces strict mode. Client reactivity inside async code needs care. Atmosphere packages often need forking or replacement. Approach the migration in phases. Do not flip the framework version flag first.

Meteor 3移除了Fibers。服务器端Mongo API改为异步模式。模块系统强制启用严格模式。异步代码中的客户端响应性需要特别处理。Atmosphere包通常需要分叉或替换。建议分阶段进行迁移，不要先切换框架版本标志。

Recommended strategy

推荐策略

Update the project to the latest 2.x release.
Run the app with
```
WARN_WHEN_USING_OLD_API=true meteor run
```
. The console logs every sync-API call that needs an async sibling, giving you a to-do list before the framework flip.
Migrate server-side sync Mongo calls to
```
*Async
```
siblings while still on 2.x. Trace each changed function through every server-side caller: await where the caller consumes the value, forward Promises deliberately, and restructure sync-only boundaries. Stop only at an async-capable framework boundary. See
```
references/async-rewrites.md
```
and
```
references/call-vs-callAsync.md
```
. A community jscodeshift codemod automates the easy cases, but it misses non-standard collection imports (for example,
```
meteor/<publisher>:collections
```
). Review the diff by hand, then audit callback Promise ownership and collection argument shapes.
Audit Atmosphere packages. Find replacements or fork outdated ones; pin
```
api.versionsFrom(['2.x', '3.0'])
```
. See
```
references/package-triage.md
```
. Save
```
.meteor/versions
```
and npm lockfile checkpoints so package-major changes remain distinguishable from Meteor.
Upgrade to Meteor 3.x.

Sweep implicit globals; rewrite to

const

export

import

. See

references/module-system.md

Audit Blaze helpers and
```
Tracker.autorun
```
blocks for lost reactivity after
```
await
```
. See
```
references/client-reactivity.md
```
.

Replace iterators that contain

await

(

forEach

map

filter

) with

for...of

Promise.all

. See

references/js-iterators.md

Audit publications using internal cursor APIs (
```
_cursorDescription
```
, manual
```
sub.added
```
) and framework handlers that read invocation
```
this
```
. Both synchronous and async publish handlers may return cursors; keep cursor transforms synchronous and use ordinary functions when Meteor must bind
```
this
```
. When a package patches
```
Meteor.publish
```
with an
```
EnvironmentVariable
```
, scope
```
publish.call
```
at the wrapper's top level, not inside the invoked handler. Verify invocation context before and after
```
await
```
. See
```
references/publications.md
```
and
```
references/other-breaking-changes.md
```
.

For TypeScript projects, install

zodern:types

and update

tsconfig.json

. See

references/typescript-migration.md

For React projects, decide whether to adopt the Suspense-aware
```
react-meteor-data
```
import. See
```
references/react-migration.md
```
, then use
```
meteor-react
```
for current hook, scaffold, and build guidance.

将项目更新至最新的2.x版本。
使用
```
WARN_WHEN_USING_OLD_API=true meteor run
```
命令运行应用。控制台会记录所有需要替换为异步等效API的同步API调用，为你在切换框架版本前提供一份待办事项清单。
仍在2.x版本时，将服务器端同步Mongo调用迁移至
```
*Async
```
等效方法。追踪每个修改函数的所有服务器端调用者：在调用者消费值的地方添加await，有意传递Promise，并重构仅支持同步的边界。仅在支持异步的框架边界处停止操作。详见
```
references/async-rewrites.md
```
和
```
references/call-vs-callAsync.md
```
。社区提供的jscodeshift代码转换工具可自动化处理简单场景，但会遗漏非标准集合导入（例如
```
meteor/<publisher>:collections
```
）。需手动审查差异，然后审核回调Promise的所有权和集合参数格式。
审核Atmosphere包。寻找替代包或分叉过时的包；设置
```
api.versionsFrom(['2.x', '3.0'])
```
。详见
```
references/package-triage.md
```
。保存
```
.meteor/versions
```
和npm锁文件检查点，以便区分包的重大变更与Meteor本身的变更。
升级至Meteor 3.x。
清理隐式全局变量；将其重写为
```
const
```
或使用
```
export
```
/
```
import
```
。详见
```
references/module-system.md
```
。
审核Blaze助手和
```
Tracker.autorun
```
块，检查
```
await
```
之后是否丢失响应性。详见
```
references/client-reactivity.md
```
。

将包含

await

的迭代器（

forEach

、

map

、

filter

）替换为

for...of

或

Promise.all

。详见

references/js-iterators.md

。

审核使用内部游标API（
```
_cursorDescription
```
、手动
```
sub.added
```
）的发布内容，以及读取调用上下文
```
this
```
的框架处理器。同步和异步发布处理器都可以返回游标；保持游标转换为同步模式，当Meteor必须绑定
```
this
```
时使用普通函数。当某个包使用
```
EnvironmentVariable
```
修补
```
Meteor.publish
```
时，在包装器的顶层作用域调用
```
publish.call
```
，而不是在调用的处理器内部。验证
```
await
```
前后的调用上下文。详见
```
references/publications.md
```
和
```
references/other-breaking-changes.md
```
。

对于TypeScript项目，安装

zodern:types

并更新

tsconfig.json

。详见

references/typescript-migration.md

。

对于React项目，决定是否采用支持Suspense的
```
react-meteor-data
```
导入。详见
```
references/react-migration.md
```
，然后使用
```
meteor-react
```
获取当前钩子、脚手架和构建相关指南。

Symptom router

症状路由表

Symptom	Reference
`TypeError: Collection.findOne is not a function`	`references/async-rewrites.md`
`Method returns undefined` or returns a `Promise`	`references/async-rewrites.md`
Downstream caller receives or reads from a `Promise`	`references/async-rewrites.md`
Cron, hook, timer, or event callback drops a Promise	`references/async-rewrites.md`
Read method receives `$set` , `$push` , or another modifier	`references/async-rewrites.md`
`allow` / `deny` validator needs an async database read	`references/async-rewrites.md`
`Meteor.call` callback never fires	`references/call-vs-callAsync.md`
`ReferenceError: X is not defined` at startup	`references/module-system.md`
Template renders, no data, Minimongo empty	`references/module-system.md`
Iron Router controller silently does not run	`references/module-system.md`
`{{> partial}}` renders nothing in Blaze	`references/module-system.md`
Page renders but live data never updates	`references/client-reactivity.md`
Blaze helper returns a `Promise`	`references/client-reactivity.md`
Cursor `transform` errors with "returned a Promise"	`references/publications.md`
`sub.added` writes never reach the client	`references/publications.md`
Method or publication loses `this.userId`	`references/publications.md`
Atmosphere package fails to resolve or build	`references/package-triage.md`
`forEach` / `map` / `filter` with `await` skips items	`references/js-iterators.md`
Middleware on `WebApp.connectHandlers` not firing	`references/webapp-express.md`
Route uses an unnamed wildcard after Meteor 3.1	`references/webapp-express.md`
`rawCollection` callback never fires	`references/other-breaking-changes.md`
Patched publication loses `Meteor.userId()` or async context	`references/other-breaking-changes.md`
`meteor reset` did not wipe the local Mongo	`references/other-breaking-changes.md`
`Method stub (X) took too long` console warning	`references/call-vs-callAsync.md`
"Cannot enlarge memory array" during `meteor update`	`references/other-breaking-changes.md`
External callback lost `this.userId` or env vars	`references/other-breaking-changes.md`
Monkey-patched `Meteor.publish` never runs	`references/other-breaking-changes.md`
`meteor/*` imports resolve to `any` in TypeScript	`references/typescript-migration.md`
`useTracker` or `useSubscribe` not re-running	`references/react-migration.md`

症状	参考文档
`TypeError: Collection.findOne is not a function`	`references/async-rewrites.md`
`Method returns undefined` 或返回 `Promise`	`references/async-rewrites.md`
下游调用者接收或读取 `Promise`	`references/async-rewrites.md`
Cron、钩子、定时器或事件回调丢弃Promise	`references/async-rewrites.md`
读取方法接收 `$set` 、 `$push` 或其他修饰符	`references/async-rewrites.md`
`allow` / `deny` 验证器需要异步数据库读取	`references/async-rewrites.md`
`Meteor.call` 回调从未触发	`references/call-vs-callAsync.md`
启动时出现 `ReferenceError: X is not defined`	`references/module-system.md`
模板渲染但无数据，Minimongo为空	`references/module-system.md`
Iron Router控制器静默未运行	`references/module-system.md`
Blaze中 `{{> partial}}` 未渲染任何内容	`references/module-system.md`
页面已渲染但实时数据从未更新	`references/client-reactivity.md`
Blaze助手返回 `Promise`	`references/client-reactivity.md`
游标 `transform` 报错“returned a Promise”	`references/publications.md`
`sub.added` 写入从未到达客户端	`references/publications.md`
方法或发布内容丢失 `this.userId`	`references/publications.md`
Atmosphere包解析或构建失败	`references/package-triage.md`
含 `await` 的 `forEach` / `map` / `filter` 跳过部分项	`references/js-iterators.md`
`WebApp.connectHandlers` 上的中间件未触发	`references/webapp-express.md`
Meteor 3.1之后路由使用未命名通配符	`references/webapp-express.md`
`rawCollection` 回调从未触发	`references/other-breaking-changes.md`
修补后的发布内容丢失 `Meteor.userId()` 或异步上下文	`references/other-breaking-changes.md`
`meteor reset` 未清除本地Mongo数据库	`references/other-breaking-changes.md`
控制台出现“Method stub (X) took too long”警告	`references/call-vs-callAsync.md`
`meteor update` 期间出现“Cannot enlarge memory array”	`references/other-breaking-changes.md`
外部回调丢失 `this.userId` 或环境变量	`references/other-breaking-changes.md`
猴子补丁的 `Meteor.publish` 从未运行	`references/other-breaking-changes.md`
TypeScript中 `meteor/*` 导入解析为 `any` 类型	`references/typescript-migration.md`
`useTracker` 或 `useSubscribe` 未重新运行	`references/react-migration.md`

Anti-patterns

反模式

Do not run
```
meteor update --release=3
```
first. Async-convert and package-triage on 2.x first.
Do not global-replace
```
findOne
```
with
```
findOneAsync
```
. Many callers need rewriting, not just
```
await
```
.
Do not mechanically rewrite client Minimongo calls to async. Both APIs work on the client. Prefer sync calls in naturally synchronous Blaze and Tracker code; use async calls in shared or already-async flows. Wrap reactive reads after an
```
await
```
with
```
Tracker.withComputation
```
.
Do not rely on Iron Router controller naming-convention lookup. Pass
```
controller:
```
explicitly on every route.
Do not mix
```
await
```
and
```
.then()
```
in the same function. Pick one.
Do not assume implicit globals work. Every top-level identifier in 3.x must be
```
const
```
,
```
let
```
, or
```
export
```
-ed.
Do not invent async replacements.
```
Meteor.userId()
```
remains synchronous inside methods and publications; there is no
```
Meteor.userIdAsync()
```
.
Do not use an arrow as a method or publication handler when it reads framework-bound
```
this
```
. An arrow ignores the invocation context Meteor supplies.
Do not rewrite
```
api.addFiles
```
or
```
api.export
```
only because the app moved to Meteor 3. They remain supported for Atmosphere packages.

不要先运行
```
meteor update --release=3
```
。应先在2.x版本完成异步转换和包梳理。
不要全局将
```
findOne
```
替换为
```
findOneAsync
```
。许多调用者需要重写，而不仅仅是添加
```
await
```
。
不要机械地将客户端Minimongo调用重写为异步。两种API在客户端都可用。在自然同步的Blaze和Tracker代码中优先使用同步调用；在共享或已异步的流程中使用异步调用。在
```
await
```
之后的响应式读取需用
```
Tracker.withComputation
```
包裹。
不要依赖Iron Router控制器的命名约定查找。在每个路由上显式传递
```
controller:
```
参数。
不要在同一个函数中混合使用
```
await
```
和
```
.then()
```
。选择其中一种方式。
不要假设隐式全局变量仍可正常工作。3.x版本中所有顶级标识符必须是
```
const
```
、
```
let
```
或通过
```
export
```
导出。
不要自行发明异步替代方法。
```
Meteor.userId()
```
在方法和发布内容中仍为同步；不存在
```
Meteor.userIdAsync()
```
。
当方法或发布内容处理器需要读取框架绑定的
```
this
```
时，不要使用箭头函数。箭头函数会忽略Meteor提供的调用上下文。
不要仅因为应用迁移到Meteor 3就重写
```
api.addFiles
```
或
```
api.export
```
。它们在Atmosphere包中仍受支持。

另请参阅

Async:

async-rewrites.md

call-vs-callAsync.md

async-cheatsheet.md

js-iterators.md

removed-functions.md

Runtime:

module-system.md

client-reactivity.md

publications.md

webapp-express.md

other-breaking-changes.md

Project:

package-triage.md

typescript-migration.md

react-migration.md

eval-cases.md

Current Meteor React integration after the upgrade:
```
meteor-react
```
.

异步相关：

async-rewrites.md

、

call-vs-callAsync.md

、

async-cheatsheet.md

、

js-iterators.md

、

removed-functions.md

。

运行时相关：

module-system.md

、

client-reactivity.md

、

publications.md

、

webapp-express.md

、

other-breaking-changes.md

。

项目相关：

package-triage.md

、

typescript-migration.md

、

react-migration.md

、

eval-cases.md

。

升级后的当前Meteor React集成：
```
meteor-react
```
。

进一步阅读（可选）

Real-world migration write-ups for context, not for fixing specific issues. The symptom router above is sufficient on its own. Open

references/community-case-studies.md

only when the user asks for narrative case studies or wants to calibrate effort and timeline.

提供真实世界的迁移案例分析，用于了解背景，而非修复特定问题。上述症状路由表已足以解决问题。仅当用户询问叙事性案例研究或希望评估工作量和时间线时，才查看

references/community-case-studies.md

。

migrate-to-meteor-3

Original

Translation

Migrate a Meteor 2.x application to Meteor 3.x

将Meteor 2.x应用迁移至Meteor 3.x

Recommended strategy

推荐策略

Symptom router

症状路由表

Anti-patterns

反模式

See also

另请参阅

Further reading (optional)

进一步阅读（可选）