migrate-to-meteor-3

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

Meteor 3 移除了 Fibers。服务端 Mongo API 现为异步。模块系统会强制使用严格模式。在异步代码中的客户端响应式行为需要谨慎处理。Atmosphere 软件包通常需要分叉或替换。请分阶段进行迁移。不要先切换框架版本标志。

推荐策略

对于 3.6-beta.3 或 3.6-rc.0，请在更新前使用先前版本准备保留的本地数据。

1. 将项目更新到最新的 2.x 版本。
2. 使用 WARN_WHEN_USING_OLD_API=true meteor run 运行应用。控制台会记录每个需要异步对应版本的同步 API 调用，为你提供切换框架版本前的待办清单。
3. 在仍使用 2.x 时，将服务端同步 Mongo 调用迁移到 *Async 对应版本。沿每个已更改函数的所有服务端调用者追踪：在调用者使用返回值时执行 await，有意传递 Promise，并重构仅支持同步操作的边界。只有到达支持异步操作的框架边界时才停止。请参阅 references/async-rewrites.md 和 references/call-vs-callAsync.md。社区维护的 jscodeshift codemod 可自动处理简单情况，但会遗漏非标准集合导入（例如 meteor/<publisher>:collections）。请手动检查差异，然后审查回调中的 Promise 归属和集合参数形状。
4. 审查 Atmosphere 软件包。寻找替代品，或分叉过时的软件包；将 api.versionsFrom(['2.x', '3.0']) 固定下来。请参阅 references/package-triage.md。保存 .meteor/versions 和 npm 锁文件检查点，以便将软件包主版本变更与 Meteor 变更区分开来。
5. 升级到选定的 Meteor 3.x 版本。
6. 清理隐式全局变量；改写为 const 或 export / import。请参阅 references/module-system.md。
7. 检查 Blaze 帮助器和 Tracker.autorun 代码块，确认 await 后是否丢失响应式行为。请参阅 references/client-reactivity.md。
8. 将包含 await 的迭代器（forEach、map、filter）替换为 for...of 或 Promise.all。请参阅 references/js-iterators.md。
9. 检查使用内部游标 API（_cursorDescription、手动调用 sub.added）的发布，以及读取调用上下文 this 的框架处理程序。同步和异步发布处理程序都可以返回游标；保持游标转换为同步，并在 Meteor 必须绑定 this 时使用普通函数。当软件包通过 EnvironmentVariable 修补 Meteor.publish 时，应在包装器顶层对 publish.call 进行作用域限定，而不是在被调用的处理程序内部。请在 await 前后验证调用上下文。请参阅 references/publications.md 和 references/other-breaking-changes.md。
10. 对于 TypeScript 项目，请检查目标版本和现有的声明提供程序。保留可正常工作的 @types/meteor 或 zodern:types 设置。Meteor 3.6-beta.1 通过 meteor types 增加了显式原生选择加入方式；更早的版本仍采用旧工作流。请参阅 references/typescript-migration.md，然后使用 meteor-typescript 处理提供程序变更和检查。
11. 对于 React 项目，请决定是否采用支持 Suspense 的 react-meteor-data 导入方式。请参阅 references/react-migration.md，然后使用 meteor-react 获取当前的 Hook、脚手架和构建指南。

症状路由表

症状	参考
TypeError: Collection.findOne is not a function	references/async-rewrites.md
方法返回 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 helper 返回 Promise	references/client-reactivity.md
Cursor 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

反模式

• 不要先运行 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-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。

如需查看指定的案例分析，请阅读 references/community-case-studies.md；修复问题时请使用症状路由器。