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

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功能因此绝大多数应用升级后无需改代码即可继续运行。但仍有两处需要开发者主动处理以便为后续版本铺平道路Cordova iOS 启动屏配置键迁移——旧式 key 被标记为废弃需要在mobile-config.js中替换为新 keyMongoDB 5.0 兼容性——Meteor 内部升级了 MongoDB Node.js Driver3.6 → 4.3.1涉及连接参数、游标计数、oplog 解析等多个层面的行为变化。下文分别展开说明。二、CordovaiOS 启动屏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,Default2x~universal~comany,Default2x~universal~comcom,Default3x~universal~anycom,Default3x~universal~comany,Default2x~iphone~anyany,Default2x~iphone~comany,Default2x~iphone~comcom,Default3x~iphone~anyany,Default3x~iphone~anycom,Default3x~iphone~comany,Default2x~ipad~anyany,Default2x~ipad~comany]替换之后还需要按 Apple 要求的新尺寸重新准备对应的启动图资源。依据 tools/cordova/builder.js 中记录的合法 key 及其尺寸约定可整理出如下配置速查表新 key目标设备/场景参考尺寸pxios_universal所有 2x 设备未声明设备/模式专属图时兜底2732×2732ios_universal_3x所有 3x 设备兜底2208×2208Default2x~universal~comany所有 2x 设备竖屏1278×2732Default2x~universal~comcom所有 2x 设备横屏窄1334×750Default3x~universal~anycom所有 3x 设备横屏宽2208×1242Default3x~universal~comany所有 3x 设备竖屏1242×2208Default2x~iphone~anyanyiPhone SE/6s/7/8/XR1334×1334Default2x~iphone~comanyiPhone SE/6s/7/8/XR 竖屏750×1334Default2x~iphone~comcomiPhone SE/6s/7/8/XR 横屏窄1334×750Default3x~iphone~anyanyiPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max2208×2208Default3x~iphone~anycomiPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max 横屏宽2208×1242Default3x~iphone~comanyiPhone 6s Plus/7 Plus/8 Plus/X/XS/XS Max 竖屏1242×2208Default2x~ipad~anyanyiPad Pro 12.9/11/10.5/9.7/7.92732×2732Default2x~ipad~comanyiPad Pro 系列竖屏1278×2732Android 侧仍使用android_universal288×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.jsrawCollection() { 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.tscount(applySkipLimit?: boolean)的默认值为true。3.5 2.6 中 MongoDB 相关核心变更清单为了让 Meteor 核心包兼容 MongoDB Node.js Driver 4.3.x本版本做了大量内部改动。绝大多数不会影响你的日常编码但官方建议在升级前充分测试应用因为 Meteor 与 MongoDB 的交互方式发生了许多变化。变更要点如下驱动内部操作结果格式变化如果依赖rawCollection的返回结果请重新核对预期格式useUnifiedTopology不再是可选参数默认即为truenative parser 不再是可选参数连接中默认falsepoolSize不再是可选参数使用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.tsoplog 新格式翻译层如果读取或依赖 oplog 的任何行为请阅读oplog_v2_converter.js当前仓库中为 TypeScript 实现 packages/mongo/oplog_v2_converter.tsupdate/insert/remove 语义保持 Meteor 风格不变但内部改用replaceOne/updateOne/updateMany。若直接使用rawCollection且仍按旧驱动风格调用将看到弃用提示waitForStepDownOnNonCommandShutdownfalse不再需要spawn MongoDB 进程时无需再传_synchronousCursor._dbCursor.operation不再是合法字段如需读取选项改用_synchronousCursor._dbCursor.(GETTERS)例如_synchronousCursor._dbCursor.readPreference副本集默认写关注变化MongoDB v5 下默认写关注为w: majorityDocker 开发环境提示如果本地用 Docker 容器跑 MongoDB可能需要在 mongodb URI 中追加directConnectiontrue以规避新驱动默认开启的 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由于本版本对核心包改动较多官方给出了如下分步迁移建议在一个独立分支中把应用升级到 Meteor 2.6meteor update --release 2.6搭建一个带 MongoDB 5.x 的staging预发布环境并让应用使用上一步的分支代码。注意当时 Atlas 无法迁移到免费 MongoDB 5.x 实例官方是在付费集群上完成验证的2022 年 2 月之后情况可能变化在 staging 数据库中恢复生产数据或用能够复现生产场景的方式填充数据将应用的MONGO_URL指向这个运行 MongoDB 5.x 的新数据库在此环境运行端到端测试若没有完善的端到端测试建议进行充分的人工测试端到端或人工测试稳定后即可视为完成了 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、skey数组操作与嵌套对象等字段描述变更而 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.4Migrating to Meteor 2.4从 2.3Migrating to Meteor 2.3从 2.2Migrating to Meteor 2.2从 2.0Migrating to Meteor 2.0从 1.12Migrating to Meteor 1.12从 1.11Migrating to Meteor 1.11从 1.10.2Migrating to Meteor 1.10.2从 1.10Migrating to Meteor 1.10从 1.9.3Migrating to Meteor 1.9.3从 1.9Migrating to Meteor 1.9从 1.8.3Migrating to Meteor 1.8.3从 1.8.2Migrating to Meteor 1.8.2从 1.8Migrating to Meteor 1.8从 1.7Migrating to Meteor 1.7从 1.6Migrating to Meteor 1.6从 1.5Migrating to Meteor 1.5从 1.4Migrating to Meteor 1.4从 1.3Migrating 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 中追加directConnectiontrueAtlas M0/M2/M5 用户确认升级到 Meteor 2.6避免与自动升级后的 5.0 集群失联走一遍 3.7 节的 staging 验证流程端到端测试 oplog 依赖功能专项验证后再发布生产。参考资源迁移指南原文guide/source/2.6-migration.md移动端配置构建实现tools/cordova/builder.jsrawCollection/rawDatabase实现packages/mongo/collection/collection.jsmongo包使用说明含 npm mongodb 直连方式packages/mongo/README.mdoplog v2 转换器实现packages/mongo/oplog_v2_converter.tsoplog 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考