Cocos Creator 引擎错误码手册EngineErrorMap.md 全解析与调试实战指南【免费下载链接】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导读EngineErrorMap.md是 Cocos Creator 引擎本仓库 cocos-engine官方维护的错误码 ↔ 错误信息对照总表收录了从 0100 到 16419 共数百条引擎级错误、警告与提示信息的英文原文。本指南将带你理解这套错误码体系的组织方式、它在引擎源码中的实际消费链路warnID/errorID/getError、核心错误码的分类速查以及看到错误码后如何反向定位源码的实战排查方法。读完本文你将能够快速读懂控制台中的Error 12103之类的输出并精准跳转到对应模块的源码定位根因。说明本文所有内容均以当前仓库 EngineErrorMap.md 及 cocos/core/platform/debug.ts 等源码为依据编写。一、认识 EngineErrorMap.md引擎的错误字典1.1 文件概况EngineErrorMap.md位于仓库根目录共3982 行、约71KB采用极简的 Markdown 结构组织以### 0100这样的四到五位数字作为锚点错误码 ID紧随其后的段落即为该错误码对应的英文错误信息模板其中%s、%d、%s为运行时填充的参数占位符部分条目带有!-- DEPRECATED --HTML 注释标记表示该错误码对应 API 已废弃仅在历史代码路径中保留。例如文件开头的两条### 0100 %s not yet implemented. ### 0200 You should specify a valid DOM canvas element.这种数字 ID 文本模板的设计使错误信息与代码解耦引擎源码中只传数字 ID 与参数具体文案统一由错误映射表输出。这样做的好处是体积与可读性发布包无需携带完整文案控制台仅输出Error 12103, please go to ...#12103之类的紧凑信息可本地化/可维护文案集中维护在单一文件中可检索错误码 ID 稳定便于搜索引擎与开发者快速定位。1.2 错误码命名空间的总体布局从文件内容推断从源码结构看EngineErrorMap.md的编号区间按引擎模块进行粗粒度分区具体归属可结合下方源码映射章节进一步确认错误码区间主要涉及模块依据消息内容归纳0100 / 0200引擎基础能力、DOM 画布1000 – 1099Action 动作系统多数已废弃1100 – 1199场景 / 效果Effect设置1200 – 1299Director 导演类、场景加载、渲染管线1300模型池1400 – 1499废弃 API 提示、cc.js工具1500 – 1599Scheduler 调度器1600 – 1699Node 节点系统addChild、zIndex等1700 – 1799Atlas / 图集节点1800 – 1899事件监听器Keyboard / Touch 等2100 – 2199Layer 图层2200 – 2299设计分辨率 / 适配策略2300 – 2399触摸 MAX_TOUCHES 限制2400 – 2499WebGL 旧版渲染2600 – 2799Sprite / SpriteBatchNode2800 – 2899SpriteFrame 缓存2900 – 2999TextureAtlas 纹理图集3000 – 3199Texture 纹理HTML5 / WebGL 相关多为废弃项3200文件缺失3300 – 3301SpriteFrame 九宫格边距超限3500 – 3521事件派发、设备运动事件权限3600 – 3661CCClass 类系统、property装饰器使用规范含大量实用示例3700 – 3702Prefab 预制体加载3800 – 3823Node / Component 组件生命周期addComponent、removeComponent等3900 – 3943动画系统AnimationClip、骨骼动画、root motion、材质 uniform 绑定4000 – 4013字体 / Label4100padding 属性废弃4200 – 4202Mask 遮罩WebGL / Canvas 模式限制4300 – 4303PageView / ScrollView4400RichText 富文本 img 标签4500 – 4501Graphics 绘图Feature Cropping 裁剪4600 – 4601脚本缺失、wasm 加载失败4900 – 4935资源加载管线loadRes、下载器、Loader5000 – 5001对象销毁double destroy5100 – 5204plist、localStorage、Web Audio5300 – 5304反序列化deserialize5400 – 5406cc.js工具类5500 – 5517property属性定义规范5600 – 5603场景 / 引用节点生命周期5700 – 5902数学工具、MotionStreak6000 – 6036粒子系统含 PNG/TIFF 解码错误6200 – 6302网格槽位、模板缓冲stencil6400 – 6402AssetLibrary6500 – 6501Widget 对齐组件6600 – 6601Collider 碰撞体6700 – 6706Canvas、Polygon、RenderRoot2D6800 – 6801事件回调参数6900 – 6905实例化instantiate7100 – 7101Enum 枚举7200 – 7243TiledMap / TMX 瓦片地图7300 – 7301旧版属性7400 – 7511DragonBones 与 Spine 骨骼动画7600 – 7607RenderTexture 渲染纹理7700 – 7805VideoPlayer、浏览器能力限制7900 – 7909数学矩阵 / 四元数8000 – 8003TIFF 位图解码8100 – 8109Shader 编译 / GLProgram8200 – 8401RigidBody、Camera、旧资源引用方式9000 – 9009Stencil 管理器、网格缓冲、全屏9100 – 9101纹理尺寸限制9200 – 9202view 视图 / 窗口9300 – 9302UI 静态缓冲 / Sampler9600 – 9644物理系统cannon.js / builtin / ammo 能力限制10001 – 10002网格顶点数 / 变形目标数超限11000WebGL 上下文丢失12001 – 12110渲染与材质系统blend 状态、Pass、自定义管线、UBO12100 – 12101字体图集、资源销毁13100 – 13104CCON 二进制格式14000状态机转换过载Marionette 动画图14100Pool 对象池14200 – 14204静态网格、meshopt 解码器14300世界变换零缩放14400 – 14401Spline 样条15000 – 15004渲染算法IBL 环境光、CSM 阴影、相机清除标志15100相机天空盒警告16000 – 16003通用废弃 / 移除提示带版本号16101 – 16304效果 / 覆盖资源 / UIRenderer / 反射探针 / 皮肤材质16305 – 16419杂项加速计、GL 格式转换、framebuffer、shader 编译、MissingScript、Tween、ProgressBar、层系统、Spine 缓存模式等以上分区基于文件内错误消息文本归纳供快速浏览使用精确到模块的消费位置请结合下文源码映射。二、从错误码到文案引擎源码如何消费这份字典2.1 核心消费入口cocos/core/platform/debug.ts错误码的运行时消费逻辑集中在 cocos/core/platform/debug.ts。关键函数如下function getTypedFormatter (type: Log | Debug | Warning | Error | Assert): (id: number, ...args: StringSubstitution[]) string { return (id: number, ...args: StringSubstitution[]): string { const msg DEBUG ? (debugInfos[id] || unknown id) : ${type} ${id}, please go to ${ERROR_MAP_URL}#${id} to see details.; if (args.length 0) { return msg; } return DEBUG ? formatString(msg, ...args) : ${msg} Arguments: ${args.join(, )}; }; }这段代码揭示了两个重要事实开发模式DEBUG下引擎通过一个debugInfos映射表由EngineErrorMap.md生成取出完整文案并用formatString将%s/%d占位符替换为运行时参数发布模式非DEBUG下为了减小包体控制台只输出精简信息例如Error 12103, please go to ${ERROR_MAP_URL}#12103 to see details.开发者需要凭 ID 回查本文档。2.2 五个带 ID 的日志接口debug.ts在文件底部统一导出了以下五个面向 ID 的日志接口debug.tsexport function logID (id: number, ...optionalParams: StringSubstitution[]): void { ... } // 普通日志 export function debugID (id: number, ...optionalParams: StringSubstitution[]): void { ... } // 调试日志 export function warnID (id: number, ...optionalParams: StringSubstitution[]): void { ... } // 警告 export function errorID (id: number, ...optionalParams: StringSubstitution[]): void { ... } // 错误 export function assertID (condition: boolean, id: number, ...optionalParams: StringSubstitution[]): void { ... } // 断言此外还有一个非输出型接口getError用于在不开日志的情况下把错误码渲染成字符串再交给上层处理export function getError (errorId: number, ...param: StringSubstitution[]): string { return errorFormatter(errorId, ...param); }2.3 引擎各模块中的实际调用示例在真实源码中EngineErrorMap.md的 ID 被各模块直接引用。以下是从仓库中检索到的典型例子可自行打开对应文件验证错误码文案见 EngineErrorMap.md源码消费位置16308illegal index count!cocos/2d/assembler/label/bmfontUtils.ts、cocos/2d/assembler/sprite/tiled.ts2626Unrecognized fill type in bar fillcocos/2d/assembler/sprite/bar-filled.ts3300 / 3301Rect width exceeds maximum margin: %s/Rect height ...cocos/2d/assets/sprite-frame.ts12103Custom pipeline create shader %s failed...自定义渲染管线模块见 cocos/rendering 目录以 3300 为例sprite-frame.ts中的调用形如errorID(3300, ${this.name}/${texture.name}, maxX, texture.width);这印证了文档模板中的%s与formatString占位符替换是一一对应的。三、高频错误码分类速查与实战解读以下按最容易在开发中遇到的场景从原文档中挑选并解读典型错误码文案均引自 EngineErrorMap.md。3.1 场景加载与 Director1200 段1206 / 1211loadScene: The scene index to load (%s) is out of range.—— 使用场景索引加载时越界说明场景未加入构建列表或索引错误1208 / 1213loadScene: Failed to load scene %s because %s is already being loaded.—— 场景重复加载冲突1209 / 1214loadScene: Can not load the scene %s because it was not in the build settings before playing.——最常见错误之一目标场景未勾选进 Build Settings运行时director.loadScene会失败1210 / 1215Failed to preload %s, %s—— 预加载失败1219Deferred render pipeline initialized. Note that non-transparent materials with no lighting will not be rendered, such as builtin-unlit.—— 延迟渲染管线初始化提示同时提醒无光照的非透明材质如builtin-unlit在延迟渲染下不可见1220Failed to set shading scale, pipelineSceneData is invalid.—— 设置shadingScale渲染分辨率缩放时管线数据无效。3.2 节点与组件1600 段、3800 段1604An Node cant be added as a child of itself.—— 节点不能添加为自己子节点1605child already added. It cant be added again—— 子节点重复添加1632Node name can not include /.—— 节点名不能包含/否则资源路径解析会出错1636 / 1637节点zIndex超出cc.macro.MAX_ZINDEX / MIN_ZINDEX时会被钳制到边界值3805Cant add component %s because %s already contains the same component.—— 同一节点重复添加同类组件3806Cant add component %s to %s because it conflicts with the existing %s derived component.—— 添加的组件与已有派生组件冲突如同时挂 Sprite 与 Mask 的相关变体3808addComponent: Should not add component (%s) when the scripts are still loading.—— 脚本尚未加载完成时禁止动态addComponent应把逻辑放到onLoad/start之后3821Cannot change hierarchy while activating or deactivating the parent.—— 父节点激活/失活过程中不能修改层级结构。3.3 动画系统3900 段3902clip is defaultClip, set force to true to force remove clip and animation state—— 删除默认动画剪辑需显式传force true3903animation state is playing, set force to true to force stop and remove clip and animation state—— 动画正在播放时移除需force true3923 / 3924Root motion 因根骨骼在动画或场景中找不到而被忽略3936Instancing/Batching enabled for non-baked skinning model or used AnimationController %s, this may result in unexpected rendering artifacts...—— 非烘焙蒙皮模型开启合批/实例化可能产生渲染异常建议在材质中关闭3940 – 3943动画绑定材质 uniform 目标失败的四级错误target 不是 material → pass 缺失 → uniform 缺失 → channel 缺失。3.4 资源加载4900 段4901loadRes: should not specify the extname in %s %s——loadRes路径不要带扩展名4914Resources url %s does not exist.—— 目标资源不在resources目录4926 / 4927音频下载器无 Web Audio 上下文 / 浏览器不支持音频4930Load image ( %s ) failed—— 图片加载失败4932关于resources目录内图集atlas的经典约束无法直接通过loadRes/getRes/releaseRes获取图集内的 SpriteFrame应先用spriteAtlas.getSpriteFrame(name)。3.5 渲染与材质12000 段、15000 段、16300 段12001BlendFactors are disabled when using custom material, please modify the blend state in the material instead.—— 使用自定义材质时混色因子需在材质 BlendState 中配置12005Material already initialized, request aborted.—— 材质重复初始化12012Cant set a material instance to a sharedMaterial slot—— 实例化材质应赋给material共享材质用sharedMaterial12102Base pass cannot override states, please use pass instance instead.—— 基础 pass 不可覆盖渲染状态需使用 pass 实例12103 / 12107 / 12108自定义管线创建 shader / render pass / render phase 失败提示重新导入所有 effectMenu → Developer → Refresh All Effect并重启 Creator15000 – 15002IBL 环境光照相关的 diffuse map / 环境贴图缺失提示15003The shadow visible distance is so small that CSM stratification is not effective...—— CSM 阴影分层失效需将shadowDistance调大15100相机 clear flag 为 skybox 但天空盒被禁用建议改为纯色。3.6 物理与物理 2D9600 段、164089600[Physics]: please check to see if physics modules are included—— 物理模块可能未被打包Feature Cropping 裁剪导致9610 – 9644各物理后端的能力差异提示例如 cannon.js 不支持胶囊体碰撞器9610、builtin 不支持网格/圆柱碰撞器9611/9612、Ammo 初始化后不支持更换 mesh9620、builtin/cannon.js 不支持 sweep 扫描函数9640/96419630A dynamic rigid body can not have the following collider shapes: Terrain, Plane and Non-convex Mesh.—— 动态刚体不能挂地形/平面/非凸网格碰撞体16408[Physics2D] b2PolygonShape failed to decompose polygon into convex polygons, node name: %s—— Box2D 多边形分解为凸多边形失败通常因自相交或过复杂轮廓引起。3.7 WebGL 与 GFX16300 段后半部分16318 – 16321glCheckFramebufferStatus()各类FRAMEBUFFER_INCOMPLETE_*错误attachment 缺失 / 尺寸不匹配 / 不支持多发生在自定义渲染纹理或后处理链中16325 / 16326shader 编译成功 / 链接失败日志16333This device does not support WebGL.16405This device does not support WebGL2.。3.8 Tween 与 UI 组件16380 段之后16386TweenAction: %s cant be converted to number—— Tween 目标属性值无法转为数值16389 / 16390pause: tween wasnt started, cant pause/resume: ...—— 未启动的 Tween 不能暂停/恢复16393start: no actions in Tween—— 空 Tween 启动16397ProgressBar FILLED mode only works when barSprites Type is FILLED!—— ProgressBar 填充模式要求 Sprite 的 Type 为FILLED。四、错误码模板中的参数占位符EngineErrorMap.md的文案大量使用 C 风格占位符运行时由formatString替换。常见占位符及其含义占位符含义示例%s字符串参数节点名、资源路径、类名、方法名等Node %s(%s) has not attached to a scene.1640%d整数参数索引、顶点数、大小texture size exceeds current device limits %d/%d9100%.4f浮点参数Updating interval from: %.4f to %.4f1507%%字面%%s x %s中的x非占位符3005多参数模板的替换顺序与errorID/warnID调用时传入的参数顺序一一对应。例如 16304 模板Skin material may need more accurate calculations, please select a head model of standard size, check the isGlobalStandardSkinObject option in the MeshRender component.不含参数而 12103 的Custom pipeline create shader %s failed...需要一个字符串参数。五、实践错误码 → 源码的逆向排查流程当控制台出现形如Error 12103 ... #12103 to see details发布模式或直接显示完整文案开发模式时可按以下步骤排查定位错误码从日志中提取数字 ID如 12103回查字典在 EngineErrorMap.md 中搜索### 12103确认文案与参数个数反查源码消费点在仓库中搜索errorID(12103/warnID(12103/getError(12103# 在 cocos 目录中检索错误码消费位置 rg 12103 cocos --type ts定位到具体模块文件后阅读调用上下文即可理解触发条件例如 12103 常来自 cocos/rendering 自定义管线创建 shader 的失败分支结合参数判断根因错误信息中带出的%s参数shader 名、资源路径等通常直接指向问题资源对照官方建议行动文档文案本身往往自带修复指引如Refresh All Effect and restart creator、please set camera clear flag to solid color。例如遇到 16397ProgressBar 填充模式可快速定位到 cocos/ui/progress-bar.ts 的实现分支检查barSprite.type与 ProgressBar 的mode是否匹配。六、废弃错误码DEPRECATED的处理建议EngineErrorMap.md中大量条目带有!-- DEPRECATED --注释例如1000 – 1031cc.ActionManager/cc.Action系列旧动作系统已被cc.Tween取代1400 – 1409各类旧 API 移除提示cc.spriteFrameCache、cc.pool、cc.audioEngine.willPlayMusic等1600 – 1639cc.Node旧接口getZOrder、boundingBox、runAction等3000 – 3118HTML5 时代纹理/图集旧接口addPVRTCImage、initWithETCFile等7400 – 7511中的部分 DragonBones / Spine 旧接口。处理建议开发者在旧项目升级时如遇到这些 ID说明代码中仍在调用废弃 API应参考文案提示通常直接给出替代 API如use cc.Tween instead、use getBoundingBox instead进行迁移编号 16000 – 16003 提供了带版本号的通用废弃/移除模板%s is deprecated since v%s.、%s is removed since v%s, please use %s instead.这类模板配合版本参数能更精确地指导升级新的引擎开发者在新增日志时应避免复用已废弃的 ID 区间优先在文件末尾追加新编号。七、扩展ErrorMap 之外的辅助调试机制DebugMode 枚举cocos/core/platform/debug.tsNONE / VERBOSE / INFO / WARN / ERROR / INFO_FOR_WEB_PAGE / WARN_FOR_WEB_PAGE / ERROR_FOR_WEB_PAGE其中后三档可在 WEB 端把日志直接绘制到画面上便于真机/浏览器排查断言语义assertID(condition, id, ...)在条件不成立时以Assert级别输出对应文案适用于绝不应当发生的不可恢复状态预定义常量与宏cc.macro.MIN_ZINDEX / MAX_ZINDEX见 1636/1637 文案、SUPPORT_TEXTURE_FORMATS见 3120 文案等宏定义于 predefine.ts与错误码提示互相印证格式错误辅助formatStringdebug.ts 同文件负责占位符替换若替换参数数量不匹配日志会以unknown id或带参数列表的形式给出提示这本身也是一种排错线索。八、结语EngineErrorMap.md表面是一份错误文案表实质上构成了 Cocos Creator 引擎运行时诊断语言的中枢向上对接debug.ts的logID/warnID/errorID/assertID/getError五类带 ID 日志接口向下被 2D 渲染、动画、资源、物理、渲染管线等各模块在关键分支处引用。掌握了错误码 ↔ 文案 ↔ 源码消费点 ↔ 修复指引这条链路就能把控制台里冰冷的数字 ID 快速翻译成可执行的修复方案。建议把本文提及的高频错误码1209、3808、4901、12001、12103、15003、16397 等当作排查速查表收藏遇到新错误码时随时回查 EngineErrorMap.md 原文并结合 cocos/core/platform/debug.ts 理解其输出机制。【免费下载链接】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），仅供参考