大一那会儿第一次在终端里敲出printf(hello world)然后看着屏幕亮起一行字那种我居然让计算机听话了的兴奋感估计每个写过代码的人都记得。后来我把这句话搬到 Cocos Creator 里想看看引擎里是不是也能一行搞定时才发现事情完全不是一个量级——Cocos Creator 的 Hello World考验的不是你会不会写字而是你能不能在场景、节点、组件、脚本、构建这条链路上把每一个环节都接对。这篇内容就是把我从零做一个 Cocos Creator Hello World 的全过程拆开讲包括版本怎么选、Hello World 有几种做法、脚本为什么挂了不报错、打包 APK 时到底踩了哪些坑。适合刚接触引擎的新手也适合从其他语言转过来、想快速建立引擎心智模型的朋友。1. 为什么引擎里的 Hello World 是完全另一回事1.1 从一行 printf 到一帧渲染中间隔了多少层在 C 语言里printf之所以能一行出结果是因为编译器帮你把标准库、运行时、终端输出设备全接好了你只需要关心字符串本身。Cocos Creator 不一样它跑的是一个游戏循环引擎每一帧都会去遍历场景里的节点树检查每个节点上挂的组件决定哪些需要重新计算变换、哪些需要重绘。你想在屏幕中央显示一个 Hello World实际发生的是这么一串动作场景被加载 → 节点树被构建 → Label 组件被激活 → 字体资源被解析 → 字形被排版成顶点数据 → 渲染管线把这些顶点提交给 GPU → 屏幕刷新。所以Hello World在这里真正的含义是你成功让引擎从资源加载到渲染这条链路完整地跑通了一帧。这也是为什么新手最容易卡住的地方往往不是代码写错而是资源没挂上、场景没保存、脚本没绑定、构建参数没配。我见过太多人在编辑器里预览得好好的一打包 APK 就黑屏问题根本不在逻辑而在链路中间断了某一环。理解这一点之后你看待 Hello World 的心态就会变——它不再是一个验证语法的小练习而是一次全链路的最小闭环验证。把这条链路走通一次后面做真正的项目时你就知道每一环该去哪找问题。1.2 这个项目到底适合谁上手我在社区里看过很多提问能明显分成几类人他们做 Hello World 的目的其实完全不同。第一类是零基础新手可能连编程都没系统学过冲着做游戏来的。对他们来说Hello World 的意义是建立我能操作这个工具的信心重点应该放在编辑器可视化操作上先别碰复杂脚本。第二类是有编程基础但没接触过游戏引擎的人比如写过后端、写过前端、写过 C 语言课设。这类人容易犯的毛病是想用代码解决一切一上来就想用纯脚本动态创建所有东西结果因为不熟悉引擎的生命周期和资源系统反而绕远路。对他们来说Hello World 的价值在于搞清声明式编辑器拖拽和命令式代码创建的关系。第三类是从 Unity 或者 Cocos 2.x 转过来的人。他们概念都有就是 API 和工具链变了。这类人需要的是版本差异对照表而不是从零科普。提示先想清楚自己属于哪一类再决定 Hello World 怎么练。用错方法不是浪费时间是给自己建立错误的第一印象。1.3 建立正确的引擎心智模型场景树、节点、组件在做任何操作之前这个概念必须掰清楚不然你会一直处于照着教程点但不知道为什么这么点的状态。Cocos Creator 用的是一个组件化实体系统。你可以这样类比整个游戏是一个舞台Scene场景舞台上有演员Node节点演员身上可以贴标签、穿衣服、戴道具Component组件。演员本身不会自己动是身上的行为组件在驱使它动。一个节点可以挂多个组件比如同时挂 Label显示文字和自定义脚本控制逻辑。这个模型带来一个非常关键的推论节点是容器组件才是功能。很多新手会问Label 节点怎么用代码改文字其实 Label 是组件不是节点你拿到的this.label是组件引用改的是组件的string属性。搞混节点和组件是后面所有坑的源头。再补一个容易忽略的点场景树是有层级的。父节点移动所有子节点跟着移动坐标系是相对的。这意味着你把 Label 放在 Canvas 下面和直接放在场景根下表现会完全不同。Canvas 是 UI 渲染的容器所有 UI 元素基本都应该放在它下面否则可能出现节点明明在场景里但屏幕上就是不显示的情况。2. 环境与版本新手最容易折在这一步2.1 版本怎么选2.x 还是 3.x这个问题我被问过无数次直接给结论新项目一律选 3.x 的稳定版除非你有明确的存量项目维护需求。原因不复杂。3.x 用了 TypeScript 作为主要脚本语言装饰器写法更接近现代前端开发习惯渲染管线重构过对新平台的支持也更及时。2.x 大量项目用的是 JavaScript 的cc.Class写法这套 API 在 3.x 里基本被替换掉了两者代码不通用。如果你在网上搜教程会看到大量 2.x 的内容复制过来在 3.x 里报错这是新手最大的困惑源之一。对比项Cocos Creator 2.xCocos Creator 3.x主要脚本语言JavaScriptcc.ClassTypeScript装饰器组件声明方式properties 字段property 装饰器命名空间cc.xxx从 cc 模块按需导入渲染管线旧管线重构后的管线新特性支持逐步停止持续推进我个人的建议是认准一个版本配套教程也认准同一个大版本。跨版本抄代码比抄错代码更浪费时间因为你连报错都看不懂。2.2 安装与项目创建的实际步骤现在 Cocos Creator 的安装走的是 Dashboard 路线Dashboard 是个类似版本管理器 项目启动器的东西。步骤大致如下去官网下载 Dashboard 安装包装完打开。在 Dashboard 的编辑器页签里下载你需要的引擎版本。这里注意Dashboard 本身和编辑器版本是分开的你可以同时装多个编辑器版本。切到项目页签点新建选择模板。填项目名、选存储路径点创建等编辑器启动。第一次启动编辑器会比较慢因为它要初始化项目缓存、编译引擎脚本。如果卡在正在加载先别急着强退看下控制台有没有进度。真正卡死的概率不高多数是磁盘慢。注意项目路径不要带中文、不要带空格、不要放在同步盘目录里。这三个是原生构建阶段报错的经典来源尤其是 Android 打包时路径里有中文会直接导致编译工具报无法识别的路径。2.3 项目模板怎么选目录结构长什么样新建项目时会给几个模板Empty空白、Hello World、2D 示例、3D 示例等。我的建议是第一次直接选 Hello World 模板先把它跑起来看效果再回头新建一个空白项目自己从零搭一遍。这样做的好处是你先看到成功的状态长什么样再去自己搭遇到问题时有对照。纯从零开始搭新手很容易在某个看不见的配置上出错然后陷入我明明都做了为什么不行的循环。创建完之后项目目录会长这样项目根目录/ ├── assets/ # 你的资源脚本、图片、场景、预制体都在这 ├── library/ # 引擎导入资源后生成的缓存不要手动改 ├── local/ # 本地配置 ├── profiles/ # 编辑器配置 ├── settings/ # 项目设置 ├── temp/ # 临时文件 ├── package.json # 项目依赖信息 └── tsconfig.json # TypeScript 配置这里最关键的一条经验你所有的工作都发生在assets目录里其他目录都可以理解成引擎自动生成的别碰。library和temp删掉重建是安全的引擎会重新生成但如果你手动往里面塞东西下次导入就可能被清掉。我见过有人把图片直接放到library里然后到处问为什么编辑器里看不到这个资源。3. 三种做法把 Hello World 显示出来3.1 方式一纯编辑器操作不写一行代码这是最适合零基础的方式全程可视化。在assets里右键新建一个场景命名Main。双击打开场景层级管理器里应该已经有一个 Canvas 节点。选中 Canvas右键 → 创建 → UI 组件 → Label。这时 Canvas 下多了一个 Label 节点。选中这个 Label 节点在属性检查器里找到 Label 组件的 String 属性把内容改成Hello World。再调一下位置把 Position 的 X、Y 都设成 0让它居中。点编辑器上方的预览按钮浏览器里就能看到文字了。这套操作看起来简单但里面有三个关键点值得说清楚。第一Label 必须放在 Canvas 下。因为 UI 渲染依赖 Canvas 提供的渲染上下文和适配规则你把 Label 放到场景根节点下它可能渲染出来但不受屏幕适配影响换个分辨率就跑到屏幕外去了。第二Position 是相对父节点的。Canvas 默认在屏幕中心所以 Label 设成 (0,0) 就是相对 Canvas 居中。这个坐标系逻辑要一开始就建立不然做复杂布局时会晕。第三String 属性支持多行但不自动换行排版长文本需要配合 Overflow 属性设置成 CLAMP 或 RESIZE_HEIGHT再指定 ContentSize。这个细节新手经常忽略导致文字超出屏幕。3.2 方式二挂脚本用代码控制文字纯编辑器方式能出效果但不算真正写代码。接下来把文字交给脚本控制。先在assets下新建一个文件夹scripts右键新建 TypeScript 脚本命名HelloWorld。3.x 生成的模板大概长这样import { _decorator, Component, Node } from cc; const { ccclass, property } _decorator; ccclass(HelloWorld) export class HelloWorld extends Component { start() { } update(deltaTime: number) { } }然后把它改成控制 Label 的版本import { _decorator, Component, Label, log } from cc; const { ccclass, property } _decorator; ccclass(HelloWorld) export class HelloWorld extends Component { property(Label) label: Label null!; start() { log(Hello World from script); if (this.label) { this.label.string Hello World我是脚本写进来的; } } }写完保存回到编辑器把脚本拖到 Canvas 或者 Label 节点上然后在属性检查器里把 Label 节点拖到脚本组件的label属性槽里。这一步叫绑定引用很多人漏掉结果运行时报Cannot read property string of null。这里的property(Label)是关键。它告诉引擎这个字段需要序列化并且在编辑器里暴露成一个可以拖拽的插槽。label: Label null!里的null!是 TypeScript 的非空断言语法只是为了让类型检查通过实际值会在编辑器绑定后注入。你要是写 JavaScript那用 2.x 的cc.Class写法也是一样的逻辑只是声明方式变成properties: { label: cc.Label }。3.3 方式三纯代码动态创建理解引擎的运行时如果你想把引擎到底怎么组织场景这件事彻底搞明白就试试全代码创建一个节点都不在编辑器里预先摆。import { _decorator, Component, Node, Label, UITransform, Color } from cc; const { ccclass } _decorator; ccclass(DynamicHello) export class DynamicHello extends Component { start() { const node new Node(DynamicLabel); this.node.addChild(node); const uiTransform node.addComponent(UITransform); uiTransform.setContentSize(400, 100); const label node.addComponent(Label); label.string Hello World动态创建; label.fontSize 40; label.lineHeight 50; label.color new Color(255, 255, 255, 255); node.setPosition(0, 0, 0); } }这段代码的信息量很大拆开看new Node(DynamicLabel)创建了一个空节点此时它什么都没有。this.node.addChild(node)把它挂到当前脚本所在节点下面这一步不做节点就不在场景树里渲染系统根本不会管它你连错误都看不到就是纯黑屏。这是新手最容易踩的静默失败。node.addComponent(UITransform)给节点加上 UI 变换组件UI 元素必须有它才能参与 UI 布局计算。addComponent(Label)加上文字组件之后通过label.string设置内容。setPosition用的是相对父节点的坐标。实操心得动态创建的节点一定要检查它有没有被加进场景树。判断方法很简单看它的parent是不是 null。如果 null说明它是个孤儿节点跑在内存里但永远不会渲染。我最早写代码时被这个坑了整整一个下午。4. 打包 APK从预览到真机的完整链路4.1 构建面板里每个参数到底在填什么编辑器预览只是跑在浏览器里真正的产物是原生包。打开项目 → 构建发布平台选 Android会看到一堆参数。逐项说几个决定成败的发布路径构建产物的输出目录默认在项目根下的build。这个路径和项目路径一样别带中文和空格。初始场景勾选你的Main场景。如果不勾打开就是黑屏因为引擎不知道先加载哪个场景。包名Package NameAndroid 应用的唯一标识格式类似com.company.game必须是反向域名风格至少两段每段只能用字母、数字、下划线不能有中划线不能以数字开头。这个填错打包必失败。API Level / 目标 SDK决定了运行环境的最低要求。简单说目标 SDK 太高老设备装不上最低 SDK 太低会缺一些新 API。新手建议先用默认值跑通再按需调整。签名Keystore调试阶段可以用引擎自带的调试签名正式发布必须用自己的 keystore。签名信息包括路径、密码、别名、别名密码四项缺一项就签不出来。加密脚本 / 压缩纹理这些属于优化项第一次跑通可以先不开减少变量。我建议第一次构建时所有能关的优化全关掉只求跑通。等你确认链路没问题了再一项一项开启去调优。一次改一堆参数然后出问题你会连排查方向都找不到。4.2 从构建产物到能装的 APK点构建之后引擎会做几件事编译脚本、合并资源、生成原生工程在build/android/proj目录下。构建本身成功不代表能出 APK它只是把工程准备好了真正的编译要靠 Android 原生的构建工具链。拿到原生工程之后有两条路一是用 Android Studio 打开build/android/proj然后 Build → Generate Signed Bundle/APK按向导走。这条路直观适合不熟命令行的人。二是命令行直接编cd build/android/proj ./gradlew assembleDebug编完之后 APK 一般在proj/build/outputs/apk/debug/下面。assembleDebug出的是调试包能装能跑但不能上架。要出正式包就用assembleRelease但它要求你配好签名否则 gradle 会直接拒绝。命令行这条路我更喜欢因为它报错信息完整、可复现、能写进脚本。Android Studio 有时候会把 gradle 的原始错误包装一遍反而不好定位。4.3 原生工具链的准备工作这一步是新手淘汰率最高的地方。要编 APK你的机器上至少需要三样东西依赖作用常见问题JDK编译 Java/Kotlin 部分版本过高或过低都可能导致 gradle 不兼容Android SDK提供构建工具和平台库路径没配或没装对应 API Level 的 SDKNDK编译 C 引擎部分版本不匹配会直接编译失败这三个东西版本是强绑定的不是说随便装个最新的就行。我的经验是以你当前引擎版本官方文档推荐的组合为准别自作主张升级。引擎发布时会声明适配过的 JDK、NDK 版本照着配能省掉九成玄学报错。环境变量也要配到位ANDROID_SDK_ROOT或者ANDROID_HOME指到 SDK 目录JAVA_HOME指到 JDK 目录。配完之后在新终端里echo $JAVA_HOME验证一下确认生效。很多找不到命令其实就是环境变量写在了一个没生效的终端会话里。提示如果你用的是 macOS 或者 Linux路径里的空格和权限问题更常见Windows 上路径反斜杠和编码问题更常见。跨平台的坑不太一样排查思路却是一致的——看构建日志里的第一条错误从那里往下读。5. 常见问题与排查速查5.1 脚本、文字、渲染这三类典型的看起来没反应我做这个 Hello World 的过程中遇到最多的不是崩溃而是静默失败不报错但就是没效果。这类问题分三种对应三种排查思路。脚本不执行先确认脚本有没有挂到节点上。脚本文件存在不等于参与运行只有挂到场景里的节点上生命周期才会被调用。还要确认脚本里的类名和文件名对得上3.x 里装饰器ccclass(HelloWorld)的名字要和引用一致。中文显示不出来或显示成方框这是字体问题。Label 用的是位图字体或者系统字体默认字体可能不包含中文字形。解决办法是导入一个包含中文的 TTF 字体在 Label 的 Font 属性里指定它。我第一次显示中文时满屏方框折腾了半天才发现是字体子集化的问题。文字有值但不显示检查三件事——节点是否在 Canvas 下、UITransform 的 ContentSize 是否够大、Label 的 Color 里 Alpha 是不是 0。这三条是渲染不出来的主要嫌疑。// 一个快速自检的脚本片段 start() { log(脚本执行了); // 验证脚本是否被调用 log(父节点是, this.node.parent?.name); // 验证节点是否在场景树里 if (this.label) { log(label 引用正常当前文字:, this.label.string); } else { log(label 引用为 null检查是否绑定了); } }这几行打印看着朴素但能在一分钟内把问题范围缩到三分之一。排查最重要的不是技巧是先定位在哪一层断了。5.2 构建阶段的报错分类构建 APK 的报错看着吓人其实能归类报错关键词大概率原因处理方向SDK location not foundSDK 路径没配检查 local.properties 或环境变量Unsupported class file versionJDK 版本不匹配换成引擎推荐版本package name invalid包名格式不符合规范检查段数、字符、开头NDK not configuredNDK 缺失或版本不对按引擎文档装对应版本keystore not found签名路径写错或文件不存在用绝对路径重新指定中文路径相关报错项目或输出路径含中文换到纯英文路径重新构建这张表我建议存下来构建报错时先扫一遍关键词能省掉一大半百度时间。经验是绝大多数构建失败都不是代码问题是环境和路径问题。还有一个很隐蔽的构建成功但一打开就黑屏。这种情况八成是初始场景没勾选或者勾了但场景文件没保存。我强烈建议养成习惯——构建前按一下 CtrlS把当前场景保存了再点构建。编辑器里改的东西不保存是不会写进文件的构建读的是文件。5.3 几个从实战里攒下来的心得第一Hello World 一定要自己从零做一遍全链路。别满足于跑通官方示例官方示例能跑通不代表你懂链路自己搭一遍会在每个环节都遇到问题解决问题才是学到的部分。第二控制变量法排查。出问题时一次只改一个东西改完立刻验证。我见过有人一次改五个配置然后重启、重构建、重装最后也不知道是哪个改对了。第三把控制台当第一现场。浏览器的 F12 控制台、编辑器底部的日志、构建输出窗口、gradle 日志这四个地方的信息按顺序看基本没有定位不了的问题。新手最容易犯的错是看到报错就跳过结果在一个问题上卡三天。第四版本严格对齐。引擎版本、JDK、NDK、SDK、gradle 插件版本这五个版本之间存在兼容矩阵。攒一套能跑通的版本组合记录下来下次直接复用别每次重新试。第五给工程建个备份习惯。原生构建有时会把生成目录改得很乱出问题时删掉build和library重新生成往往比修更省事。养成定期把assets目录单独备份的习惯这样无论工程被折腾成什么样你真正的劳动成果都在。我个人的体会是Cocos Creator 的 Hello World 真正的价值不在于那行文字显示出来的一瞬间而在于它逼着你把场景怎么加载、节点怎么组织、组件怎么生效、资源怎么进包、原生怎么编译这一整条链路都摸了一遍。这条链路走通一次你后面做任何东西都有了坐标——出了问题你知道该在哪个环节去找。最后再说一个小技巧。如果你将来要从头做项目不妨保留一个自己的迷你工程里面只有 Hello World 加一个空场景构建参数全部配好、能一次成功出包。每次引擎或工具链升级后先用这个迷你工程验证一下确认没问题再动正式项目。用一个小工程当探针比在正式项目上试错靠谱得多。