企业官网建设流程全解析

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 } }

字段语义说明如下：

注意：文档示例中的//注释与尾随逗号仅用于说明字段，实际 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是一段描述版本匹配区间的表达式字符串，支持三种形态：简单条件、复合条件与通配符条件。

简单条件

复合条件

复合条件把多个简单条件组合成区间表达式，遵循两条规则：

• 空格是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分支则用于扩展多个互不相交的合法区间。

通配符条件

通配符条件用于表达整段版本的匹配范围：

x不区分大小写，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）、<=（lessequal）
• >（greater）、<（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()是核心校验函数，流程如下：

1. 从引擎根目录package.json读取当前引擎版本（tryGetEngineVersion，缺省回退 3.6.0）；
2. 读取项目native/目录下的common/cocos-version.json（记录生成该 native 目录时的引擎版本）；
3. 若该版本文件不存在，则比较模板common/Classes下的Game.h、Game.cpp与项目内的同名文件是否完全一致，一致则自动补写版本文件放行；
4. 若版本文件存在，则用versionParser.parse(versionRange)解析compatibility-info.json中的版本区间，并用cond.match(projEngineVersion)判断项目生成版本是否落在合法区间内；
5. 区间匹配通过时，还会顺带检测项目版本是否比当前引擎更新，若更新则给出 warning（通常意味着项目由更高版本引擎生成）；
6. 匹配失败则报错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.0；>=3.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 合法性：该文件必须是严格合法的 JSON，README 示例中的注释与尾随逗号仅用于示意，不可直接复制进真实文件；
• 项目侧逃生舱：当项目 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