企业官网建设流程全解析

Meteor 2.6 迁移指南：Cordova 启动屏升级与 MongoDB 5.0 全面兼容

【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor

本指南面向从 Meteor 2.5（或更早版本）升级到 Meteor 2.6 的应用开发者，系统梳理本版本两大核心变化：Cordova iOS 启动屏（Launch Screen）由旧式图片 key 向 storyboard 兼容 key 的迁移，以及 MongoDB Node.js Driver 从 3.6 升级到 4.3.1 后带来的 MongoDB 5.x 支持、连接选项与游标行为变更。读完本文，你将掌握App.launchScreens的迁移对照表、Cursor.count()行为变化、rawCollection适配要点，以及一份可落地的 MongoDB 4.x → 5.x 分阶段升级演练方案。

一、2.6 版本迁移总览

Meteor 2.6 的大部分新特性要么在后台以向后兼容的方式直接生效，要么属于可选（opt-in）功能，因此绝大多数应用升级后无需改代码即可继续运行。但仍有两处需要开发者主动处理，以便为后续版本铺平道路：

1. Cordova iOS 启动屏配置键迁移——旧式 key 被标记为废弃，需要在mobile-config.js中替换为新 key；
2. MongoDB 5.0 兼容性——Meteor 内部升级了 MongoDB Node.js Driver（3.6 → 4.3.1），涉及连接参数、游标计数、oplog 解析等多个层面的行为变化。

下文分别展开说明。

二、Cordova：iOS 启动屏（Launch Screens）迁移

2.1 新增能力：暗黑模式启动屏

Meteor 2.6 起，你可以为 iOS 和 Android 配置暗黑主题专属的启动屏。做法是给App.launchScreens中对应的 key 传入一个对象：

App.launchScreens({ ios_universal: { src: 'light-image-src-here.png', srcDarkMode: 'dark-mode-src-here.png', }, });

{src, srcDarkMode}对象形式目前仅对 iOS 生效（Android 暗黑启动屏需遵循 Android 官方暗黑主题指引，其路径值仍要求为字符串）。

这一点可以从构建工具的实现得到印证：在 tools/cordova/builder.js 中，App.launchScreens的实现会遍历传入的 key，对android相关 key 校验其值必须是字符串（否则直接抛错），并对未知 key 给出unknown key in App.launchScreens configuration. The key may be deprecated.的告警；随后将图片路径映射合并进构建器的 splash 资源清单，交由 Cordova 生成各尺寸启动图。

2.2 旧 key 废弃与新 key 对照

iOS 上App.launchScreens的旧式启动屏 key 现已废弃，取而代之的是与 iOS storyboard 尺寸类（size class）规范对齐的新 key。废弃的 key 如下：

['iphone5','iphone6','iphone6p_portrait','iphone6p_landscape','iphoneX_portrait','iphoneX_landscape','ipad_portrait_2x','ipad_landscape_2x','iphone','iphone_2x','ipad_portrait','ipad_landscape']

请将这些 key 逐一替换为对应新 key（顺序一一对应）：

['ios_universal','ios_universal_3x','Default@2x~universal~comany','Default@2x~universal~comcom','Default@3x~universal~anycom','Default@3x~universal~comany','Default@2x~iphone~anyany','Default@2x~iphone~comany','Default@2x~iphone~comcom','Default@3x~iphone~anyany','Default@3x~iphone~anycom','Default@3x~iphone~comany','Default@2x~ipad~anyany','Default@2x~ipad~comany']

替换之后，还需要按 Apple 要求的新尺寸重新准备对应的启动图资源。依据 tools/cordova/builder.js 中记录的合法 key 及其尺寸约定，可整理出如下配置速查表：

Android 侧仍使用android_universal（288×288 dp）作为合法 key，且值必须是字符串路径。

三、MongoDB 5.0 支持

3.1 背景与兼容矩阵

Meteor 2.6 之前的版本支持 MongoDB Server 4.x；从本版本开始，Meteor 将 MongoDB Node.js Driver 从 3.6 升级到4.3.1，从而支持 MongoDB Server 5.x。这次升级在撰写本指南（2022 年 1 月）时是必要的：MongoDB Atlas 计划于 2022 年 2 月将 M0（免费集群）、M2、M5 等计划的集群自动迁移到 MongoDB 5.0，这也被视为 MongoDB 官方推动 5.0 全面普及的信号。

需要特别提醒的是：如果你正在 MongoDB Atlas 的 M0/M2/M5 计划上运行应用，必须升级到 Meteor 2.6才能在 MongoDB 自动升级到 5.0 后正常连接与交互；如果不在这些计划上，继续使用旧版 MongoDB Server 与旧版 Meteor 也不会有问题。

Meteor 2.6 对 MongoDB Server 的兼容版本为：5.1、5.0、4.4、4.2、4.0、3.6（与 Node.js Driver 4.3.x 的支持范围一致）。也就是说，即便你的数据库还没升级到 5.x，也可以放心运行最新版 Meteor。

3.2 本地嵌入式 MongoDB：记得执行 meteor reset

如果你在本地环境使用 Meteor 自带的嵌入式 MongoDB，升级后需要执行一次：

meteor reset

以使本地数据库正常工作。注意meteor reset会清空本地数据库中的全部数据，执行前请确认没有需要保留的内容。

3.3 rawCollection() 与底层驱动 API 变更

rawCollection是 Meteor 提供的直通 Node.js MongoDB Driver 的入口，让你能自由使用驱动层能力，但这也意味着你需要自己为所用驱动版本的 API 变化负责——Meteor 内部虽已迁移到 MongoDB 5.x 与 Driver 4.x，却不会（也不应）替你改写业务代码或包中对rawCollection的调用。

从源码可以看到，rawCollection()与rawDatabase()均为服务端专用方法，直接透传底层 driver 对象（见 packages/mongo/collection/collection.js）：

rawCollection() { var self = this; if (!self._collection.rawCollection) { throw new Error('Can only call rawCollection on server collections'); } return self._collection.rawCollection(); }

关于驱动 API 变化，一个典型的例子是aggregate：旧版collection.rawCollection().aggregate()支持回调（callback）风格，新驱动不再接受回调；aggregate().toArray()现在返回 Promise。因此这类调用需要改写为基于 Promise /await的写法。

如果你在某个第三方包中看到相关报错，请到该包所属仓库提交 issue，交由维护者依据新驱动 API 修正。此外，Meteor 官方对驱动内部返回结果格式也做了适配，如果你依赖rawCollection操作的返回结果（而不只是数据库内的效果），务必核对新驱动的返回格式预期。

3.4 Cursor.count()：applySkipLimit 行为变化

find游标的count()不再支持applySkipLimit选项，该选项默认始终为true。看一个具体例子：集合中有 50 条文档，执行：

const cursor = collection.find({}, { limit: 25 });

此时cursor.fetch()返回 25 条文档，cursor.count()也是25；而在旧版本中，cursor.count()会返回 50，需要显式传入applySkipLimit才能得到 25。

现在，要获取集合中符合条件的全部文档数，需要新建一个不带 limit 的游标：

const cursorWithLimit = collection.find({}, { limit: 25 }); const cursorWithNoLimit = collection.find({}); // cursorWithLimit.fetch() => 返回 25 条文档 // cursorWithNoLimit.count() => 返回 50

无需担心创建多个游标的开销：find只是查询语句的封装，连续创建两个或更多游标是完全可以的，并不会更慢。该行为在类型定义中也有对应说明（见 packages/mongo/mongo.d.ts）：count(applySkipLimit?: boolean)的默认值为true。

3.5 2.6 中 MongoDB 相关核心变更清单

为了让 Meteor 核心包兼容 MongoDB Node.js Driver 4.3.x，本版本做了大量内部改动。绝大多数不会影响你的日常编码，但官方建议在升级前充分测试应用，因为 Meteor 与 MongoDB 的交互方式发生了许多变化。变更要点如下：

• 驱动内部操作结果格式变化：如果依赖rawCollection的返回结果，请重新核对预期格式；
• useUnifiedTopology不再是可选参数：默认即为true；
• native parser 不再是可选参数：连接中默认false；
• poolSize不再是可选参数：使用maxPoolSize/minPoolSize实现同等行为。这一点在源码中可印证，例如 packages/mongo/mongo_connection.js 对minPoolSize的透传处理，以及 packages/mongo/oplog_tailing.ts 中 oplog 监听连接使用{ maxPoolSize: 1, minPoolSize: 1 }的方式；
• fields选项废弃：当前维护了一层到projection字段（推荐用法）的翻译层，直到下一个 minor 版本才开始输出告警。类型定义中同样标注了@deprecated use projection instead（见 packages/mongo/mongo.d.ts）；
• _ensureIndex现在会显示弃用提示（类型定义中已标注@deprecated，见 packages/mongo/mongo.d.ts）；
• oplog 新格式翻译层：如果读取或依赖 oplog 的任何行为，请阅读oplog_v2_converter.js（当前仓库中为 TypeScript 实现 packages/mongo/oplog_v2_converter.ts）；
• update/insert/remove 语义保持 Meteor 风格不变：但内部改用replaceOne/updateOne/updateMany。若直接使用rawCollection且仍按旧驱动风格调用，将看到弃用提示；
• waitForStepDownOnNonCommandShutdown=false不再需要：spawn MongoDB 进程时无需再传；
• _synchronousCursor._dbCursor.operation不再是合法字段：如需读取选项，改用_synchronousCursor._dbCursor.(GETTERS)，例如_synchronousCursor._dbCursor.readPreference；
• 副本集默认写关注变化：MongoDB v5 下默认写关注为w: majority；
• Docker 开发环境提示：如果本地用 Docker 容器跑 MongoDB，可能需要在 mongodb URI 中追加directConnection=true，以规避新驱动默认开启的 Service Discovery（服务发现）特性。

另外，如果你使用 Meteor 内置 MongoDB 在本地运行应用，升级到 2.6 后同样需要执行一次meteor reset。

3.6 迁移场景一：保持 MongoDB Server 版本不变

如果你不更换 MongoDB Server 版本，即使使用了rawCollection结果，也不需要改动任何代码。但由于 Meteor 内部与 MongoDB 的交互方式为适配新驱动做了大量调整，强烈建议在生产发布前仔细测试应用。

官方在真实应用与自动化测试套件中做了大量验证，据信已修复过程中发现的所有问题；但 Meteor 与 MongoDB 的交互面非常广且开放，不同的使用场景仍可能暴露不同问题。请特别检查那些你认为「非传统用法」的 MongoDB 调用点。

3.7 迁移场景二：从 MongoDB 4.x 升级到 5.x

由于本版本对核心包改动较多，官方给出了如下分步迁移建议：

1. 在一个独立分支中把应用升级到 Meteor 2.6：

   meteor update --release 2.6

2. 搭建一个带 MongoDB 5.x 的staging（预发布）环境，并让应用使用上一步的分支代码。注意：当时 Atlas 无法迁移到免费 MongoDB 5.x 实例，官方是在付费集群上完成验证的（2022 年 2 月之后情况可能变化）；
3. 在 staging 数据库中恢复生产数据，或用能够复现生产场景的方式填充数据；
4. 将应用的MONGO_URL指向这个运行 MongoDB 5.x 的新数据库；
5. 在此环境运行端到端测试；若没有完善的端到端测试，建议进行充分的人工测试；
6. 端到端（或人工）测试稳定后，即可视为完成了 MongoDB 5.x 的数据库版本迁移，后续按常规数据库迁移流程管理即可。

官方声明未发现这些改动引入的问题，但仍建议重点检查应用行为，尤其是那些「非传统用法」的 MongoDB 调用。特别注意 oplog 相关功能：MongoDB 5.0 的 oplog 格式经历了大量变化，Meteor 为此专门编写了转换器来继续理解 oplog 的新格式，因此如果你的应用依赖 oplog（即 Meteor 的实时数据同步系统）实现复杂特性或查询，务必验证相关功能是否正常。

MongoDB 5.0 还移除了一些 Meteor 曾经使用的已废弃方法，因此建议对所有重要操作进行回归测试。

3.8 深入：oplog v2 格式转换器

MongoDB 5.0 引入了全新的 oplog v2 格式，条目形如：

{ $v: 2, diff: Diff }

其中Diff是递归结构，通过i（嵌套更新）、u（顶层更新）、d（删除/$unset）、s<key>（数组操作与嵌套对象）等字段描述变更；而 Meteor 的实时查询系统（Livequery / oplog tailing）历史上只处理$set/$unset风格的事件。为此 Meteor 提供了转换器oplogV2V1Converter（见 packages/mongo/oplog_v2_converter.ts），其职责是把 v2 的diff结构翻译成等价的$set/$unset操作序列，并将路径拍平为点号记法，同时保留 EJSON 自定义类型与 ObjectID 的结构。

在 packages/mongo/oplog_observe_driver.js 中可以看到该转换器被正式引入 oplog 观察驱动；配套的测试 packages/mongo/tests/oplog_v2_converter_tests.js 用大量用例覆盖了嵌套更新、数组按索引更新/删除、EJSON 自定义类型（如EJSONtail）、对象字段展开等场景。如果你的应用依赖 oplog 实现实时功能，可以借助这些测试理解转换规则，进而设计自己的验证用例。

四、从 2.5 之前的版本升级？

本文档只覆盖了 Meteor 2.4 → 2.6（以及 2.5 → 2.6）之间的变化。如果你从早于 2.5 的版本升级，可能还有一些本指南未列出的注意事项，请按升级路径逐一查阅更早的迁移指南：

• Migrating to Meteor 2.5（从 2.4）
• Migrating to Meteor 2.4（从 2.3）
• Migrating to Meteor 2.3（从 2.2）
• Migrating to Meteor 2.2（从 2.0）
• Migrating to Meteor 2.0（从 1.12）
• Migrating to Meteor 1.12（从 1.11）
• Migrating to Meteor 1.11（从 1.10.2）
• Migrating to Meteor 1.10.2（从 1.10）
• Migrating to Meteor 1.10（从 1.9.3）
• Migrating to Meteor 1.9.3（从 1.9）
• Migrating to Meteor 1.9（从 1.8.3）
• Migrating to Meteor 1.8.3（从 1.8.2）
• Migrating to Meteor 1.8.2（从 1.8）
• Migrating to Meteor 1.8（从 1.7）
• Migrating to Meteor 1.7（从 1.6）
• Migrating to Meteor 1.6（从 1.5）
• Migrating to Meteor 1.5（从 1.4）
• Migrating to Meteor 1.4（从 1.3）
• Migrating to Meteor 1.3（从 1.2）

五、升级检查清单

为便于落地，将本文要点浓缩为一份可直接执行的检查清单：

• 在mobile-config.js中替换 iOS 启动屏的 14 个废弃 key 为新 storyboard key，并按尺寸表重新出图；
• 如需暗黑启动屏，使用{src, srcDarkMode}对象形式（仅 iOS）；
• 本地嵌入式 MongoDB 用户执行meteor reset（注意清空数据）；
• 检查业务代码与第三方包中对rawCollection/rawDatabase的调用，重点适配 Promise 化 API（如aggregate().toArray()）；
• 排查cursor.count()依赖applySkipLimit的旧逻辑，改用无 limit 的新游标获取总数；
• 涉及连接池、拓扑、字段投影（fields→projection）、索引创建（_ensureIndex）的代码按 3.5 节清单核对；
• Docker 环境在 URI 中追加directConnection=true；
• Atlas M0/M2/M5 用户确认升级到 Meteor 2.6，避免与自动升级后的 5.0 集群失联；
• 走一遍 3.7 节的 staging 验证流程（端到端测试 + oplog 依赖功能专项验证）后再发布生产。

参考资源

• 迁移指南原文：guide/source/2.6-migration.md
• 移动端配置构建实现：tools/cordova/builder.js
• rawCollection/rawDatabase实现：packages/mongo/collection/collection.js
• mongo包使用说明（含 npm mongodb 直连方式）：packages/mongo/README.md
• oplog v2 转换器实现：packages/mongo/oplog_v2_converter.ts
• oplog v2 转换器测试用例：packages/mongo/tests/oplog_v2_converter_tests.js
• 连接与游标类型定义：packages/mongo/mongo.d.ts
• 连接选项处理：packages/mongo/mongo_connection.js

【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor