1. 项目概述：从“看”到“做”的实战跨越

如果你在搜索引擎里敲下“Cocos Creator 实战项目”，大概率会看到一堆教程、Demo和资源列表。就像我最初接触时一样，面对“awesome-cocos-creator”这类资源汇总，感觉像进了一个琳琅满目的超市，什么都好，但不知道从哪下手。看别人写的“跳一跳”复刻、棋牌游戏源码，心里痒痒的，但真到自己动手，新建一个空白项目后，却常常对着编辑器发呆：UI怎么布局才高效？代码架构怎么设计才不乱？资源怎么管理才不会“爆炸”？这些才是实战开发中真正卡脖子的地方。

今天要聊的，不是一个简单的Demo展示，而是一个具备完整工程思维的游戏开发实战项目。它不仅仅是一份源码，更是一个从零到一、贯穿了核心开发流程的“脚手架”或“样板工程”。我会基于一个经典的、易于理解的游戏类型（比如“打砖块”或“消除类”），拆解其完整的实现过程，并附上所有源码。目标是让你不仅能“运行”起来，更能理解每一行代码背后的设计意图，掌握从资源导入、场景搭建、逻辑编写、调试优化到最终打包上线的全链路实操能力。无论你是刚学完Cocos Creator基础、想找个项目练手的新手，还是有一定经验、但总感觉项目结构混乱、寻求最佳实践的中级开发者，这个实战拆解都能给你带来直接的参考价值。

2. 项目整体设计与架构思路

2.1 核心玩法与功能模块定义

我们选择一个“打砖块”（Brick Breaker）的变体作为实战项目。它规则简单，但足以覆盖游戏开发的核心模块：

1. 核心玩法：玩家控制底部的挡板左右移动，反弹小球，击碎屏幕上方的所有砖块。小球碰到砖块、墙壁和挡板有不同的物理反应，砖块被击碎后可能掉落道具（如加长挡板、加速球、额外生命等）。
2. 功能模块拆解：
   • 场景管理模块：负责游戏开始、进行中、暂停、结束、关卡选择等场景的加载与切换。
   • 游戏逻辑核心模块：包含挡板控制、小球运动与碰撞逻辑、砖块生成与销毁、道具系统、分数与生命值计算。
   • UI交互模块：主菜单、游戏内HUD（分数、生命值显示）、暂停面板、游戏结束面板、设置界面。
   • 资源与数据管理模块：统一加载和管理图片、音效、预制体（Prefab）等资源；管理游戏配置数据（如关卡布局、小球速度、砖块血量）和玩家存档数据（最高分、已解锁关卡）。
   • 物理与动画模块：利用Cocos Creator内置的物理引擎（或纯数学碰撞检测）处理碰撞；使用缓动动画（Tween）或动画组件（Animation）实现简单的UI动效和道具效果。

选择这个项目，是因为它“麻雀虽小，五脏俱全”。你不需要被复杂的游戏类型吓到，可以更专注地理解各个模块是如何协同工作的。

2.2 技术选型与工程结构规划

在动手写代码前，好的工程结构能省去后期无数重构的麻烦。

1. 脚本语言：TypeScript。这是强烈推荐的选择。相比于JavaScript，TypeScript提供了静态类型检查、更好的IDE智能提示和重构能力，对于中大型项目管理和团队协作至关重要。它能有效避免“undefined is not a function”这类运行时错误提前到编译时暴露。

2. 项目目录结构设计：

   assets/ ├── scripts/ # 所有游戏脚本 │ ├── core/ # 核心框架、管理器 │ │ ├── GameManager.ts # 游戏总控单例 │ │ ├── AudioManager.ts # 音效管理单例 │ │ ├── UIManager.ts # UI管理单例 │ │ └── DataManager.ts # 数据持久化管理 │ ├── game/ # 游戏逻辑 │ │ ├── Ball.ts # 小球控制 │ │ ├── Paddle.ts # 挡板控制 │ │ ├── Brick.ts # 砖块逻辑（可衍生不同颜色/血量的砖块） │ │ ├── Prop.ts # 道具基类与具体道具类 │ │ └── LevelManager.ts # 关卡数据加载与生成 │ ├── ui/ # UI面板控制脚本 │ │ ├── MenuPanel.ts │ │ ├── GameHUD.ts │ │ └── PausePanel.ts │ └── utils/ # 工具函数、常量定义 │ ├── Constants.ts │ └── Helper.ts ├── resources/ # 动态加载的资源 ├── scenes/ # 场景文件(.fire) ├── prefabs/ # 预制体文件(.prefab) ├── textures/ # 图片资源 ├── sounds/ # 音效资源 └── animations/ # 动画剪辑

   这样的结构清晰地将代码按职责分离，core下的管理器使用单例模式，方便全局访问；game下的脚本专注于实体行为；ui下的脚本处理界面交互。resources文件夹用于存放需要运行时动态加载的资源（如不同关卡的配置JSON）。

3. 为何采用管理器（Manager）模式？游戏开发中，像音频播放、UI切换、游戏状态控制这些功能，往往需要在多个地方调用。如果每个脚本都直接去操作cc.audioEngine或者查找Canvas下的节点，代码会高度耦合，难以维护。通过创建AudioManager、UIManager、GameManager这样的单例类，我们将功能集中管理。例如，AudioManager内部封装了播放、暂停、设置音量等方法，并可以统一管理音频ID，避免重复播放和内存泄漏。其他脚本只需调用AudioManager.instance.playSound('click')即可，实现了高内聚、低耦合。

3. 核心模块实现与代码深度解析

3.1 游戏核心逻辑：挡板、小球与碰撞

这是游戏的心脏。我们不用物理引擎的刚体，而是用更轻量、可控的2D几何碰撞检测来实现，这对于这类游戏性能更好，逻辑也更清晰。

1. 挡板控制（Paddle.ts）：

   const {ccclass, property} = cc._decorator; @ccclass export default class Paddle extends cc.Component { @property(cc.Node) private ballSpawnPos: cc.Node = null; // 小球发射位置参考点 private _moveSpeed: number = 500; private _minX: number = 0; private _maxX: number = 0; start() { // 计算挡板在屏幕内的移动边界（考虑挡板自身宽度） let worldPos = this.node.parent.convertToWorldSpaceAR(this.node.position); let leftBoundary = cc.v2(0, worldPos.y); let rightBoundary = cc.v2(cc.winSize.width, worldPos.y); this._minX = this.node.parent.convertToNodeSpaceAR(leftBoundary).x + this.node.width / 2; this._maxX = this.node.parent.convertToNodeSpaceAR(rightBoundary).x - this.node.width / 2; } update(dt: number) { // 使用键盘或鼠标/触摸控制 if (cc.sys.isMobile) { // 移动端触摸控制（简化示例：跟随触摸水平位置） let touches = cc.systemEvent.getTouches(); if (touches.length > 0) { let touchPos = this.node.parent.convertToNodeSpaceAR(touches[0].getLocation()); this.node.x = cc.misc.clampf(touchPos.x, this._minX, this._maxX); } } else { // PC端键盘控制 let dir = 0; if (cc.input.isKeyDown(cc.macro.KEY.left) || cc.input.isKeyDown(cc.macro.KEY.a)) { dir -= 1; } if (cc.input.isKeyDown(cc.macro.KEY.right) || cc.input.isKeyDown(cc.macro.KEY.d)) { dir += 1; } this.node.x += dir * this._moveSpeed * dt; this.node.x = cc.misc.clampf(this.node.x, this._minX, this._maxX); } } // 获取当前挡板顶部中心位置，用于发射小球 public getBallSpawnWorldPos(): cc.Vec2 { return this.ballSpawnPos.convertToWorldSpaceAR(cc.Vec2.ZERO); } }

   关键点：update中的移动逻辑每帧执行。我们通过cc.misc.clampf函数将挡板的x坐标限制在计算好的边界内，防止其移出屏幕。移动端控制这里做了简化，实际项目中可能需要更平滑的跟随或虚拟摇杆。

2. 小球运动与碰撞（Ball.ts）：

   @ccclass export default class Ball extends cc.Component { @property private initialSpeed: number = 300; private _rigidBody: cc.RigidBody2D = null; private _velocity: cc.Vec2 = cc.v2(0, 0); private _isLaunched: boolean = false; onLoad() { this._rigidBody = this.getComponent(cc.RigidBody2D); // 初始化速度方向（例如向上45度） let angle = Math.PI / 4; // 45度 this._velocity = cc.v2(this.initialSpeed * Math.cos(angle), this.initialSpeed * Math.sin(angle)); } launch(fromWorldPos: cc.Vec2) { this.node.position = this.node.parent.convertToNodeSpaceAR(fromWorldPos); this._isLaunched = true; } update(dt: number) { if (!this._isLaunched) return; // 基于速度向量移动 let newPos = this.node.position.add(this._velocity.mul(dt)); this.node.position = newPos; // 屏幕边界碰撞检测（顶部、左右） let ballRect = this.node.getBoundingBoxToWorld(); let winRect = cc.rect(0, 0, cc.winSize.width, cc.winSize.height); if (ballRect.xMin <= winRect.xMin || ballRect.xMax >= winRect.xMax) { this._velocity.x *= -1; // 水平反转 AudioManager.instance.playSound('wall'); } if (ballRect.yMax >= winRect.yMax) { this._velocity.y *= -1; // 垂直反转（顶部） AudioManager.instance.playSound('wall'); } // 底部掉落检测在GameManager中处理 } // 与挡板碰撞（简化版，实际应根据碰撞点调整反弹角度） onCollisionEnter(other: cc.Collider, self: cc.Collider) { if (other.node.group === 'paddle') { // 计算基于碰撞点的反弹：碰撞点越靠挡板边缘，水平速度分量越大 let hitPoint = other.world.position; let paddleCenter = other.node.parent.convertToWorldSpaceAR(other.node.position); let relativeHit = (hitPoint.x - paddleCenter.x) / (other.node.width / 2); // -1 到 1 // 设置新的速度向量，y方向始终向上，x方向根据击中位置偏移 let newSpeed = this._velocity.mag(); // 保持原速率 let maxBounceAngle = Math.PI / 3; // 最大反弹角度60度 let bounceAngle = relativeHit * maxBounceAngle; this._velocity.x = Math.sin(bounceAngle) * newSpeed; this._velocity.y = Math.cos(bounceAngle) * newSpeed; AudioManager.instance.playSound('paddle'); } else if (other.node.group === 'brick') { // 击中砖块，简单垂直反转（更复杂的可以计算法线反射） this._velocity.y *= -1; // 通知砖块被击中 let brickComp = other.node.getComponent('Brick'); if (brickComp) { brickComp.takeHit(); } AudioManager.instance.playSound('brick'); } } }

   深度解析：这里展示了两种碰撞处理思路。对于屏幕边界，我们使用包围盒检测，简单高效。对于与挡板和砖块的碰撞，我们使用了Cocos Creator的碰撞组件（Collider），并在onCollisionEnter回调中处理。挡板的碰撞反弹是亮点：我们根据小球击中挡板的相对位置（relativeHit）来计算一个反弹角度，这使得游戏操作更有深度——你可以通过移动挡板的不同位置来控制小球的反弹方向，这是许多经典打砖块游戏的核心技巧。

   注意：使用碰撞组件需要在编辑器中为小球、挡板、砖块分别添加cc.CircleCollider或cc.BoxCollider，并正确设置分组（Group）。同时，要确保在项目设置-物理中启用了物理系统（即使是2D）。对于纯几何检测，也可以不用碰撞组件，自己用cc.Rect或cc.Circle的相交判断，但碰撞组件与引擎集成更好，能处理更复杂的形状和提供碰撞回调。

3.2 数据驱动与关卡设计

硬编码关卡布局是低效的。我们将关卡数据外置为JSON文件，实现数据与逻辑分离。

1. 关卡数据格式（level_01.json）：

   { "id": 1, "name": "关卡一", "ballSpeed": 320, "paddleWidth": 120, "brickLayout": [ {"type": "red", "hp": 1, "row": 0, "col": 0}, {"type": "red", "hp": 1, "row": 0, "col": 1}, {"type": "blue", "hp": 2, "row": 1, "col": 0}, {"type": "blue", "hp": 2, "row": 1, "col": 1}, {"type": "green", "hp": 3, "row": 2, "col": 0, "prop": "expand"} // 绿色砖块被击碎后会掉落“挡板加长”道具 ], "gridWidth": 8, "gridHeight": 5 }

2. 关卡管理器（LevelManager.ts）：

   import { _decorator, Component, Node, Prefab, instantiate, JsonAsset } from 'cc'; const { ccclass, property } = _decorator; interface BrickData { type: string; hp: number; row: number; col: number; prop?: string; } interface LevelData { id: number; name: string; ballSpeed: number; paddleWidth: number; brickLayout: BrickData[]; gridWidth: number; gridHeight: number; } @ccclass('LevelManager') export class LevelManager extends Component { @property(Prefab) private brickPrefabMap: {[key: string]: Prefab} = {}; // 在编辑器中关联不同颜色砖块的Prefab private _currentLevelData: LevelData = null; private _brickNodePool: cc.NodePool = null; // 使用对象池管理砖块节点，优化性能 onLoad() { this._brickNodePool = new cc.NodePool('Brick'); // 假设Brick脚本挂在Prefab根节点 } public async loadLevel(levelId: number): Promise<boolean> { return new Promise((resolve) => { cc.resources.load(`levels/level_${levelId}`, JsonAsset, (err, asset: JsonAsset) => { if (err) { console.error(`Failed to load level ${levelId}:`, err); resolve(false); return; } this._currentLevelData = asset.json as LevelData; this.generateBricks(); resolve(true); }); }); } private generateBricks() { // 先回收所有现有砖块到对象池 // ... (回收逻辑) const layout = this._currentLevelData.brickLayout; const brickWidth = 60; // 假设每个砖块宽60像素 const brickHeight = 30; // 高30像素 const startX = - (this._currentLevelData.gridWidth * brickWidth) / 2 + brickWidth / 2; const startY = 200; // 从屏幕上方200像素开始放置 for (let data of layout) { let brickNode: cc.Node = null; if (this._brickNodePool.size() > 0) { brickNode = this._brickNodePool.get(); } else { let prefab = this.brickPrefabMap[data.type]; if (!prefab) { console.warn(`No prefab found for brick type: ${data.type}`); continue; } brickNode = instantiate(prefab); } // 设置砖块位置 brickNode.setPosition( startX + data.col * brickWidth, startY - data.row * brickHeight ); // 设置砖块数据（血量、掉落道具类型等） let brickComp = brickNode.getComponent('Brick'); if (brickComp) { brickComp.init(data.hp, data.prop); } this.node.addChild(brickNode); // 将砖块添加到关卡管理器节点下 } } // 当砖块被销毁时，回收到对象池 public recycleBrickNode(node: cc.Node) { this._brickNodePool.put(node); } }

   核心技巧：
   • 数据驱动：通过JSON配置关卡，修改关卡布局、砖块属性无需改动代码，甚至可以由策划人员独立完成。
   • 动态加载：使用cc.resources.load异步加载JSON资源，避免将所有关卡数据打包进首包。
   • 对象池（NodePool）：砖块频繁创建和销毁，使用对象池可以极大减少运行时内存分配和垃圾回收（GC）的压力，是性能优化的关键手段。注意，从对象池取出的节点，其组件上的属性会被保留，所以需要在Brick.init()方法中重置状态。

3.3 UI管理系统与状态控制

游戏状态（菜单、游戏中、暂停、结束）的切换需要与UI界面同步。

1. 游戏总控单例（GameManager.ts）：

   @ccclass('GameManager') export class GameManager { private static _instance: GameManager = null; public static get instance(): GameManager { if (!this._instance) { this._instance = new GameManager(); } return this._instance; } public gameState: GameState = GameState.Menu; // 枚举：Menu, Playing, Paused, GameOver, LevelComplete private _currentLevel: number = 1; private _score: number = 0; private _lives: number = 3; public get score(): number { return this._score; } public get lives(): number { return this._lives; } private constructor() {} // 私有构造函数，确保单例 public startGame(level: number = 1) { this._currentLevel = level; this._score = 0; this._lives = 3; this.gameState = GameState.Playing; // 通知UI管理器切换界面 UIManager.instance.switchToGameHUD(); // 加载关卡 // ... (调用LevelManager) // 初始化小球和挡板 // ... } public pauseGame() { if (this.gameState === GameState.Playing) { this.gameState = GameState.Paused; cc.director.pause(); // 暂停游戏逻辑和渲染 UIManager.instance.showPausePanel(); } } public resumeGame() { if (this.gameState === GameState.Paused) { cc.director.resume(); this.gameState = GameState.Playing; UIManager.instance.hidePausePanel(); } } public onBallLost() { this._lives--; UIManager.instance.updateLives(this._lives); if (this._lives <= 0) { this.gameOver(false); // 失败 } else { // 重置小球和挡板位置，准备重新发射 // ... } } public addScore(points: number) { this._score += points; UIManager.instance.updateScore(this._score); } private gameOver(isWin: boolean) { this.gameState = GameState.GameOver; UIManager.instance.showGameOverPanel(isWin, this._score); // 保存最高分等数据 DataManager.instance.saveHighScore(this._score); } } export enum GameState { Menu, Playing, Paused, GameOver, LevelComplete }

   GameManager作为游戏中枢，协调着游戏状态、分数、生命值，并驱动UIManager更新界面。它通常被设计成单例，方便在任何脚本中访问。

2. UI管理器（UIManager.ts）：

   @ccclass('UIManager') export class UIManager { private static _instance: UIManager = null; public static get instance(): UIManager { if (!this._instance) { this._instance = new UIManager(); } return this._instance; } private _canvasNode: cc.Node = null; private _currentPanel: cc.Node = null; // 当前活动的面板 // 通过节点路径或预制体引用持有各个UI面板 private _menuPanel: cc.Node = null; private _gameHUD: cc.Node = null; private _pausePanel: cc.Node = null; private _gameOverPanel: cc.Node = null; public init(canvasNode: cc.Node) { this._canvasNode = canvasNode; // 这里假设UI面板已经是Canvas的子节点，通过名字查找 this._menuPanel = this._canvasNode.getChildByName('MenuPanel'); this._gameHUD = this._canvasNode.getChildByName('GameHUD'); this._pausePanel = this._canvasNode.getChildByName('PausePanel'); this._gameOverPanel = this._canvasNode.getChildByName('GameOverPanel'); // 初始显示菜单 this.switchToMenu(); } public switchToMenu() { this.hideAllPanels(); this._menuPanel.active = true; this._currentPanel = this._menuPanel; } public switchToGameHUD() { this.hideAllPanels(); this._gameHUD.active = true; this._currentPanel = this._gameHUD; } public showPausePanel() { this._pausePanel.active = true; // 暂停面板通常叠加在GameHUD之上 } private hideAllPanels() { this._menuPanel.active = false; this._gameHUD.active = false; this._pausePanel.active = false; this._gameOverPanel.active = false; } // 更新HUD上的分数和生命值显示 public updateScore(score: number) { let scoreLabel = this._gameHUD.getChildByName('ScoreLabel').getComponent(cc.Label); scoreLabel.string = `分数: ${score}`; } public updateLives(lives: number) { // 可能用图标表示生命，这里简化用Label let livesLabel = this._gameHUD.getChildByName('LivesLabel').getComponent(cc.Label); livesLabel.string = `生命: ${lives}`; } }

   UI管理器的核心是控制不同UI面板的显示与隐藏。通过active属性来控制节点的激活状态，比动态加载和销毁性能更好。注意，UI管理器也需要在游戏启动时（例如在Canvas根节点的某个初始化脚本中）进行init调用。

4. 性能优化与打包发布实战

4.1 性能优化要点

当砖块数量多、道具飞舞时，性能问题就会显现。以下是几个关键优化点：

1. DrawCall合并：这是2D游戏最常见的性能瓶颈。DrawCall是CPU向GPU发起的一次绘制命令。次数越多，CPU开销越大。

   • 自动合批：Cocos Creator会对使用相同材质和纹理的静态节点（非动态更新位置、旋转、缩放）进行自动合批。确保砖块、背景等静态元素使用相同的图集（Sprite Atlas）。将多个小图片打包到一个大图集中，可以极大地减少DrawCall。
   • 手动控制：避免频繁改变节点的渲染属性（如颜色、透明度）。对于需要动态改变颜色的砖块，考虑使用不同的预制体（对应不同材质实例）而非运行时修改color属性。

2. 对象池（NodePool）的深入使用：前面在LevelManager中提到了砖块的对象池，对于小球、子弹、道具等频繁生成和销毁的游戏对象，必须使用对象池。

   // 在PropManager中管理道具对象池 export class PropManager { private _propPool: cc.NodePool = null; private _propPrefab: cc.Prefab = null; public init(prefab: cc.Prefab) { this._propPrefab = prefab; this._propPool = new cc.NodePool('Prop'); // Prop是道具的脚本 // 预创建一些对象放入池中，避免首次生成卡顿 for (let i = 0; i < 10; i++) { let propNode = instantiate(this._propPrefab); this._propPool.put(propNode); } } public spawnProp(worldPos: cc.Vec2, type: string): cc.Node { let propNode: cc.Node = null; if (this._propPool.size() > 0) { propNode = this._propPool.get(); } else { propNode = instantiate(this._propPrefab); } // 初始化道具位置和类型 propNode.setPosition(worldPos); let propComp = propNode.getComponent('Prop'); propComp.init(type); return propNode; } public recycleProp(node: cc.Node) { this._propPool.put(node); } }

   关键细节：对象池取出的节点，其所有组件onLoad、start方法不会再次调用，但onEnable和onDisable会。因此，对象的初始化逻辑（如重置位置、血量、状态）应该放在一个自定义的init()方法中，并在从对象池获取后调用。销毁逻辑（如停止定时器、清理事件监听）应放在onDisable中。

3. 避免在update中做昂贵操作：

   • 不要在update中频繁使用cc.find、getChildByName等遍历节点树的方法。应在start或onLoad中缓存引用。
   • 复杂的计算（如寻路、大量数学运算）可以考虑降低频率，比如每5帧执行一次。

4.2 多平台打包与适配

Cocos Creator的优势之一在于一键多平台发布。但不同平台有各自的“坑”。

1. 小游戏平台（微信、抖音等）：

   • 包体大小限制：微信小游戏初始包体通常有4M或8M限制。务必使用资源分包和远程资源。将首屏非必需的资源（如后续关卡资源、大量音效）放在远程服务器或分包中。
   • 代码包优化：使用引擎的“构建后压缩代码”选项。对于微信小游戏，可以开启“使用分离引擎”功能，将引擎代码从游戏代码中分离，利用微信的引擎缓存。
   • 文件系统差异：小游戏环境没有完整的Node.jsfs模块。所有资源加载必须使用cc.resources.load或cc.assetManager。玩家数据存储需使用平台提供的API，如微信的wx.setStorageSync。

2. Web平台：

   • 缓存问题：更新资源后，浏览器可能会缓存旧文件。在构建时，可以为资源文件名添加哈希值（在构建面板中勾选“MD5 Cache”）。
   • 首屏加载：WebGL上下文初始化、引擎和资源加载需要时间。设计一个美观的加载界面，并显示加载进度。使用cc.assetManager.downloader可以监听总体加载进度。

3. 原生平台（Android/iOS）：

   • 原生插件：如果需要调用手机硬件功能（如振动、陀螺仪），需要编写或使用第三方原生插件。Cocos Creator提供了JSB（JavaScript Binding）机制来调用原生代码。
   • 性能Profile：在原生平台上，可以使用Xcode的Instruments或Android Studio的Profiler来深度分析CPU、内存和GPU使用情况，这在Web端是难以做到的。

构建流程 checklist：

• [ ] 在项目设置中正确配置应用ID、应用名称、图标、启动图。
• [ ] 根据目标平台，在构建发布面板选择正确的平台，并填写必要的配置（如微信小游戏的AppID）。
• [ ] 勾选必要的构建选项：合并图集、压缩纹理、压缩代码、MD5 Cache。
• [ ] 点击构建，等待完成后，点击发布到指定目录或一键上传到小游戏后台。

5. 常见问题排查与调试技巧

在实际开发中，你一定会遇到各种奇怪的问题。这里记录一些高频问题的解决思路。

5.1 资源加载失败

• 现象：控制台报错“Failed to load asset”，图片显示为粉色方块。
• 排查：
  1. 路径错误：cc.resources.load的路径是相对于assets/resources目录的。确认你的资源是否放在resources文件夹下，以及路径字符串是否正确（大小写敏感，无需后缀名）。
  2. 资源未导入：检查资源管理器中该资源是否正常显示。有时图片拖入项目后，引擎需要时间处理导入，稍等即可。
  3. 构建后丢失：检查构建后的build目录下，该资源文件是否存在。如果不存在，可能是该资源没有被任何场景或代码引用，在构建时被剔除了。确保它在resources目录下，或者被动态加载的代码路径正确引用。

5.2 碰撞检测不生效

• 现象：物体明明穿过了，却没有触发onCollisionEnter。
• 排查：
  1. 分组设置：碰撞双方（Collider）的分组必须设置正确，并且要在项目设置-物理-碰撞矩阵中，勾选这两个分组之间的碰撞关系。
  2. 碰撞组件类型：确保两个碰撞体类型匹配（如BoxCollider对BoxCollider）。CircleCollider和BoxCollider之间可以碰撞。
  3. 节点缩放：如果节点的缩放为0，碰撞体也会失效。检查节点的scale属性。
  4. 物理系统未开启：在项目设置-物理中，确保enabled是勾选状态。

5.3 在真机上运行异常（小游戏/原生）

• 现象：在编辑器里运行正常，打包到手机或小游戏平台后白屏、报错或功能异常。
• 排查：
  1. 开发者工具调试：微信开发者工具、Chrome远程调试（Android）或Safari Web检查器（iOS）是救命稻草。查看Console中的错误信息。
  2. 平台API兼容性：代码中是否使用了浏览器特有的API（如alert,console.table）？在小游戏环境中，这些可能不存在或行为不同。使用cc.sys.platform进行条件判断。
  3. 路径大小写：某些服务器或原生平台（如Android）对文件路径大小写敏感，而Windows/Mac开发机不敏感。确保所有资源引用路径的大小写与实际文件完全一致。
  4. 异步操作顺序：真机性能差异可能导致异步加载（如cc.resources.load）的回调顺序与编辑器不同。确保关键逻辑（如游戏初始化）在所有依赖资源加载完成后再执行。

5.4 内存泄漏与性能骤降

• 现象：游戏玩一段时间后越来越卡，甚至崩溃。
• 排查与解决：
  1. 对象池滥用：只创建，不回收。确保所有通过instantiate动态创建的节点，在不使用时都通过对象池put回收，或者调用node.destroy()。
  2. 事件监听未移除：使用this.node.on('event', callback, this)注册的事件监听，如果该节点长期存在（如常驻的UI节点），通常无需手动移除（因为节点销毁时会自动清理）。但如果监听的目标是全局对象（如cc.systemEvent）或者回调函数中使用了this，在组件销毁时（onDestroy中）必须调用this.node.off('event', callback, this)或cc.systemEvent.off(...)来移除，否则回调函数无法被垃圾回收，导致内存泄漏。
  3. 定时器未清理：this.schedule或setInterval创建的定时器，在组件销毁时要在onDestroy中用this.unscheduleAllCallbacks()或clearInterval清理。
  4. 大纹理未释放：动态加载的大图，在使用完毕后，如果确定不再需要，可以调用cc.assetManager.releaseAsset(texture)来释放其内存。但需谨慎，避免释放后再次使用。

一个实用的调试习惯：在Chrome开发者工具的Memory面板，定期拍摄堆快照（Heap Snapshot），对比前后快照中Detached DOM tree和JavaScript objects的增长情况，可以精准定位内存泄漏点。对于Cocos Creator项目，关注cc.Node,cc.Component等引擎内部对象的实例数量是否异常增长。