Cocos Creator 模板版本兼容声明解析compatibility-info.json 与 VERSION_RANGE 语法完全指南【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine本文是 Cocos 引擎仓库中 templates/README.md 的技术详解围绕模板目录下compatibility-info.json文件展开说明它如何声明模板文件与历史引擎版本的兼容关系并逐条剖析VERSION_RANGE的简单条件、复合条件与通配符语法。读完本文你将掌握该版本声明文件的字段语义、可在真实工程中直接套用的版本区间写法以及它在原生打包native-pack-tool流程中触发版本校验的底层实现机制。背景模板目录与兼容性声明的用途在仓库根目录的templates/下存放着 Cocos Creator 生成各类工程模板所需的资源与工程骨架文件包括android/、ios/、mac/、windows/、linux/、ohos/、qnx/、harmonyos-next/等原生平台模板以及wechatgame/、alipay-mini-game/、taobao-mini-game/、web-desktop/、web-mobile/等发布平台模板此外还有cmake/、common/、launcher/、native/等公共与辅助模板。由于引擎版本会持续演进而模板文件尤其是原生平台的 CMake 配置、工程文件可能与某些旧版本引擎不再兼容仓库在 templates/compatibility-info.json 中集中声明了模板与之前版本的兼容关系。也就是说这份文件解决的核心问题是用某版本引擎生成的native/工程目录能否安全地被另一个版本的引擎继续使用。它是一份可兼容版本区间的声明而非执行逻辑本身——真正的校验逻辑由scripts/native-pack-tool在打包时读取并执行。compatibility-info.json 的文件结构与字段语义根据 templates/README.md 中的定义该文件的核心结构如下{ // include all supported native platforms, such as windows, ios, android, mac etc. native: // required { default: 3.6.0, // required, applied if any specific platform value is not provided windows: VERSION_RANGE // optional, supported version for Windows mac: VERSION_RANGE // optional, supported version for Mac ios: VERSION_RANGE // optional, supported version for iOS android: VERSION_RANGE // optional, supported version for Android } }字段语义说明如下字段是否必填含义native必填声明全部受支持的原生平台windows、ios、android、mac 等的兼容版本区间native.default必填默认兼容版本区间当某个具体平台未单独声明时使用该值native.windows/native.mac/native.ios/native.android可选对应平台特定的兼容版本区间优先级高于default注意文档示例中的//注释与尾随逗号仅用于说明字段实际 JSON 文件中不允许出现注释。仓库中的真实文件 templates/compatibility-info.json 内容极其精简{ native: { default: 3.6.0 } }这意味着当前模板默认要求引擎版本不低于 3.6.0且所有原生平台均未单独声明统一回落到default。如果后续某平台例如 ohos单独出现兼容性差异只需在该文件中增加对应平台字段即可例如windows: 3.6.0 3.8.0。VERSION_RANGE 语法详解VERSION_RANGE是一段描述版本匹配区间的表达式字符串支持三种形态简单条件、复合条件与通配符条件。简单条件写法含义3.6.0版本大于等于 3.6.03.5.1版本大于 3.5.13.5.1版本小于 3.5.13.5.1版本小于等于 3.5.13.3.2精确指定版本 3.3.2!3.5.0排除版本 3.5.0除 3.5.0 以外的任意版本复合条件复合条件把多个简单条件组合成区间表达式遵循两条规则空格是AND与运算3.6.0 3.7.0表示版本必须同时满足大于等于 3.6.0且小于 3.7.0即 3.6.x 全系版本||是OR或运算3.4.2 || 3.6.0表示版本为 3.4.2或者大于等于 3.6.0。文档给出的示例3.6.0 3.7.0 3.4.2 || 3.6.0 3.4.0 !3.4.2 3.5.0 || 3.6.0第三条示例可读作版本落在3.4.0与3.5.0之间且不等于 3.4.2或者精确等于 3.6.0。可以看到AND分组可以任意组合排除条件OR分支则用于扩展多个互不相交的合法区间。通配符条件通配符条件用于表达整段版本的匹配范围写法等价展开3.x3.0.0 4.0.03.4.x3.4.0 3.5.0x不区分大小写3.X、3.x均合法源码中还支持*作为通配符见下文。展开规则是通配符所在位从 0 起步上一位主版本号 1 作为上界。底层实现版本表达式的解析与匹配引擎VERSION_RANGE 并非由打包工具硬编码解析而是复用了一套独立的、基于 PEG.js 生成的版本解析器位于 native/cmake/scripts/plugin_support/plugin_cfg.pegjs语法源文件与 native/cmake/scripts/plugin_support/plugin_cfg.js生成产物。操作符与文法PEG 文法Cond规则定义了七类操作符其中两种写法等价greaterequal、lessequalgreater、less!与!not排除与裸版本号equal相等无前缀的裸版本号如3.3.2等价于精确相等版本本体Version支持三段式major.minor.patch也允许只写major或major.minor缺失位在比较时按 0 补齐。通配符Factor规则同时接受*、x、X三种写法仓库的解析器测试 native/cmake/scripts/plugin_support/test_parse.js 中即出现了3.4.*、3.4.x、3.4.X三种等价形式。AND / OR 的组合语义文法中的Conds规则把空格分隔的多个Cond组合成一个条件组组内全部匹配才通过Expression规则再用||连接多个条件组。匹配过程实现为先按||拆分为若干条件组只要有一个条件组整体匹配即判定通过同一条件组内的多个简单条件则必须全部成立。这与文档中空格是 AND、||是 OR的说明完全一致。版本比较算法版本比较的核心实现位于compareTo与test方法比较时把major、minor、patch补齐为三段并通过因子化公式(major 20) (minor 10) patch折算成一个整数后相减从而支持大于、小于、等于的数值比较而通配符版本则走match方法按位匹配major/minor/patch 任一为*即跳过该位校验。需要注意通配符只能出现在被匹配的模式一侧参与数值比较的版本不允许带通配符assertNotWildcard会抛出异常。在原生打包流程中的实际应用VERSION_RANGE 的真正消费方是scripts/native-pack-tool的原生打包工具。以基类 scripts/native-pack-tool/source/base/default.ts 为线索可以看到完整的校验调用链。读取兼容性声明tryGetCompatibilityInfo()方法读取仓库根目录下templates/compatibility-info.json依次校验文件存在性、native字段存在性、native.default字段存在性然后按当前打包平台this.params.platform取值若声明中不存在该平台字段则回落到default否则返回平台专属区间。其加载路径为Paths.enginePath/templates/compatibility-info.json与 templates/compatibility-info.json 一一对应。版本校验流程validateTemplateVersion()是核心校验函数流程如下从引擎根目录package.json读取当前引擎版本tryGetEngineVersion缺省回退 3.6.0读取项目native/目录下的common/cocos-version.json记录生成该 native 目录时的引擎版本若该版本文件不存在则比较模板common/Classes下的Game.h、Game.cpp与项目内的同名文件是否完全一致一致则自动补写版本文件放行若版本文件存在则用versionParser.parse(versionRange)解析compatibility-info.json中的版本区间并用cond.match(projEngineVersion)判断项目生成版本是否落在合法区间内区间匹配通过时还会顺带检测项目版本是否比当前引擎更新若更新则给出 warning通常意味着项目由更高版本引擎生成匹配失败则报错ErrorCodeIncompatible错误码 15004提示native/目录由不兼容版本的引擎生成从而阻止打包继续避免在错误的 CMake 工程上编译。cocos-version.json 与 skipCheck项目侧的版本标记文件是native/common/cocos-version.json由writeEngineVersion()自动生成内容包含两个字段{ version: 3.8.0, skipCheck: false }其中skipCheck是一个逃生舱当用户明确知道自己项目的 native 目录与模板版本存在差异、但仍希望继续打包时可将该字段改为true校验逻辑会打印Skip version range check by project并放行。这在项目 native 目录目录结构略有差异、但人工确认无风险的场景下非常实用仓库代码在平台目录结构校验失败时也会提示使用该字段来规避警告。单元测试佐证解析器的正确性由 native/cmake/scripts/plugin_support/test_parse.js 中的断言覆盖。例如区间3.3 3.6应匹配3.4、3.4.1、3.5.2等但不匹配3.3、3.3.2、3.6.03.4.0 !3.4.2 3.5.0 || 3.6.0应匹配3.4.1、3.5.0、3.6.0但不匹配3.4.2。这些用例与 README 中 VERSION_RANGE 语法示例一一呼应可作为验证自写区间表达式正确性的参考样例。实操建议如何编写与维护版本声明结合语法与源码给出以下实践要点默认值优先兜底始终维护native.default具体平台只有在与默认值不同时才单独声明避免冗余区间写清上下界推荐使用3.6.0 3.8.0这类显式闭区间替代容易歧义的裸版本号排除某个有已知问题的版本用!3.4.2通配符适合大跨度3.x语义清晰且与文档等价展开完全一致适合声明整个 3.x 大版本均兼容先对照测试再发布新增或修改版本区间后可参照test_parse.js的assert_match模式补充边界断言重点验证区间端点如3.6.0、3.7.0与排除版本注意 JSON 合法性该文件必须是严格合法的 JSONREADME 示例中的注释与尾随逗号仅用于示意不可直接复制进真实文件项目侧逃生舱当项目 native 目录确实需要跳过校验时编辑native/common/cocos-version.json将skipCheck置为true但应作为临时手段并尽快让模板与项目对齐。总结compatibility-info.json以极小的结构承载了模板目录与引擎版本之间的兼容契约native.default提供兜底区间平台字段提供细分覆盖VERSION_RANGE则以空格 AND、||OR、通配符展开的简洁语法表达复杂区间。其背后由 PEG 文法解析器 plugin_cfg.pegjs 提供语法支持由 native-pack-tool 在原生打包时实际执行校验。理解这一整套机制可以帮助你在升级引擎、迁移项目或扩展新平台模板时准确声明并规避版本兼容风险。【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考