企业官网建设流程全解析

1. 先想清楚：Cocos Creator 的 Hello World 到底在验证什么

1.1 从 C 语言那行 printf 说起

大一新生写下的第一个 C 语言程序，往往是这样的：引入头文件，写一个 main 函数，调用 printf 打印一行字，然后 return 0。这段代码在语法上没有任何难度，真正的价值在于它一次性验证了三件事——编译器装好了、链接器能找到标准库、运行环境能把可执行文件跑起来。只要屏幕上出现那行字，从"没有环境"到"环境可用"这道坎就算迈过去了。

Cocos Creator 的 Hello World 承担的职责其实一模一样，只不过要验证的东西从"一个编译器"变成了"一整套内容生产管线"。编辑器能不能正常启动、场景能不能保存、资源能不能被正确引用、脚本能不能被编译和加载、预览窗口能不能渲染出画面，这几件事任意一环出问题，你在后面做真正的玩法时会一头雾水，分不清是代码写错了还是环境没配好。所以我的习惯是：任何一个新版本、新机器、新团队环境，第一件事就是老老实实跑一遍 Hello World，把这条链路先焊死。

1.2 Hello World 在游戏引擎里要跨过的四道门槛

从纯文本输出到引擎渲染，中间隔着好几道普通人不太会注意的门槛，这里先把它们点出来，后面每章都会落到实处。

第一道是场景与节点系统。游戏引擎里没有"直接往屏幕上打一行字"这种操作，文字必须先成为一个节点，挂上渲染组件，再被放进一棵节点树，最后由摄像机拍下来。你要搞清楚节点、组件、场景三者之间的从属关系，否则就会出现"我明明加了 Label，屏幕上一片空白"的经典问题。

第二道是坐标系与适配。屏幕有多大、设计分辨率是多少、锚点在哪里、父节点的尺寸是多少，这些参数共同决定了一个文字节点最终落在屏幕的哪个像素上。很多人第一次做出来文字飞到屏幕外，八成就是这块没理顺。

第三道是脚本与组件的绑定关系。引擎的脚本不是被"调用"的，是被"挂载"的。你写的类必须能出现在属性检查器的添加组件列表里，挂上去之后引擎才会按生命周期回调去驱动它，这一点和写 C 语言时"写个 main 就有人执行"的直觉完全不同。

第四道是构建与打包。开发时在浏览器里预览跑通，不代表能出一个能装到手机上的 APK。原生构建涉及外部依赖、包名、ABI、签名等一堆参数，这一步是新手掉队最多的地方，也是最值得提前走一遍的地方。

1.3 谁适合跟着这篇走

如果你是完全没接触过引擎的编程新手，这篇可以当成一次完整的"开荒记录"来看，每个操作我都会说明它在干什么、为什么要这么干，而不是丢一堆菜单路径让你照点。如果你是从其他引擎或者 Cocos 2.x 转过来的老手，第 2 章之后的编辑器与工程结构差异、第 5 章的打包参数、第 6 章的踩坑表更值得你直接跳读。整篇的默认前提是 Cocos Creator 3.x 版本加 TypeScript 工作流，2.x 的差异我会在必要的地方单独点出来，因为两个大版本在这件事上的操作路径差别不小，混着看容易晕。

2. 开工前的环境与工程初始化

2.1 Dashboard 与编辑器版本的选择

Cocos Creator 的安装包里带的其实是一个 Dashboard（项目与版本的统一入口）加若干版本编辑器。Dashboard 负责管理你本机装了哪几个版本的编辑器、每个项目用哪个版本打开。这里有个很容易被忽视的细节：项目一旦用某个版本的编辑器打开并保存过，再换版本打开时会有升级提示，升级动作几乎不可逆。所以我的做法是，正式项目登记一个主版本号写进团队文档，Dashboard 里也只留主版本加一个备用版本，避免自己下意识点错。

版本选择上，新手不要追最新的大版本。选一个官方文档覆盖完整、社区资料多的稳定小版本，比如 3.8 系列里的最新补丁版。原因很实际：新手遇到的问题九成是别人已经踩过的，资料越多你越容易搜到答案；而大版本刚发布时，插件生态、教程、第三方库的适配往往滞后，你会在一些莫名其妙的地方卡住，还找不到人问。

还有一个常被忽略的操作：安装路径不要带中文和空格。原生构建阶段会调用外部命令行工具，路径里有空格会让某些脚本参数解析出错，报错信息还特别隐晦。Windows 用户尤其注意，默认装在C:\Program Files下就带空格了，直接装到D:\Cocos\这类干净路径，能省掉一堆麻烦。

2.2 新建项目时模板怎么挑

新建项目面板会给出几个模板，常见的有空白的 3D 工程、空白的 2D 工程，以及一些带示例内容的工程。做 Hello World 这件事，我建议直接选空白 2D 工程，理由有三点。

一是 2D 模板默认给你的场景结构更贴近"界面上放一行字"这种需求，节点树更干净，你不需要先把 3D 模板里的默认光源、相机参数理解一遍。二是空白模板没有预置的示例脚本和资源，你每加一个文件都是自己加的，出问题时排查范围小。三是带示例的工程虽然看着热闹，但它会引入大量你暂时不需要的概念，比如预制体、物理系统、动画状态机，新手很容易被带偏，花两小时研究示例代码而不是搞明白自己的 Hello World。

项目名字建议用英文加下划线，比如hello_world。项目路径同样不要有中文和空格。这个建议听起来像老生常谈，但它在后面构建原生工程时会真的咬你一口：某些构建工具的中间产物路径拼接对非 ASCII 字符支持不好，报的错跟你写的中文项目名毫无关联，你要排查很久才能想到是路径的问题。

2.3 工程目录逐层拆解

新建完成后，先别急着打开场景，把工程根目录浏览一遍。理解这些目录各自的职责，能让你在后面遇到"改了没生效""构建报错"时更快定位。

这里有一条我用血泪换来的经验：遇到"编辑器行为异常、资源显示不对、脚本改了不生效"这类玄学问题，第一步永远是关掉编辑器，删掉 library 和 temp，重新打开工程让它重建缓存。这两个目录是纯缓存，删了不会有任何损失，重建一次通常几分钟，但能解决掉大半的诡异问题。我见过有人为了一个"Label 不显示"的问题重装了两遍编辑器，最后发现是资源缓存坏了。

另外，assets目录下的资源引用关系是有唯一标识的，直接在文件管理器里拖动或重命名资源文件，会让引用断掉，编辑器里会出现一堆命名冲突或者丢失引用。所有资源的移动、重命名、删除，都老老实实在编辑器的资源管理器面板里做，让编辑器同步更新元数据。这条规矩越早养成越好，等工程里几百个资源的时候再改习惯，代价就是一片红色的报错。

3. 不用写一行代码：先让屏幕出现自己的文字

3.1 场景、节点树与 Canvas 的坐标系

打开默认场景，你会看到层级管理器里已经有一个场景根节点，下面通常挂着一个 Canvas 节点和一个摄像机节点。先建立三个概念。

场景是一份可保存的关卡描述文件，它记录了这个场景里有哪些节点、每个节点挂了什么组件、组件的参数是什么。节点是场景里的一个位置容器，本身不渲染任何东西，它的价值在于提供坐标、旋转、缩放，以及作为子节点的父级。组件才是真正干活的，渲染、动画、脚本逻辑都以组件形式挂在节点上。

真正决定"文字画在哪里"的是 Canvas 下的坐标系。Canvas 节点上带一个 UITransform 组件，它定义了这块 UI 画布的尺寸，而这个尺寸来自项目设置里的设计分辨率。比如设计分辨率设置成 960x640，那么画布范围内，节点坐标就落在这个区间里。关键点在于：节点的位置是相对于父节点锚点的偏移，而不是屏幕绝对坐标。你把一个 Label 节点拖进 Canvas，它的位置坐标(0, 0)表示与父节点锚点重合，也就是画面中心，而不是左上角。

这也是新手第一次做的时候最常见的困惑来源：明明把位置设成(0, 0)，以为会出现在左上角，结果文字漂在正中间。搞明白"相对父节点"这五个字，后面所有 UI 布局问题都会好理解很多。

3.2 Label 组件的参数逐个说清楚

在 Canvas 上右键新建一个节点，给它添加 Label 组件，然后修改 string 属性，你就能在场景编辑器里看到文字了。但要让它在运行时表现正常，有几个参数必须理解。

Overflow 这个参数值得单独说。它大致有几种策略：不处理、自动换行后裁剪、自动换行后撑高节点、整体缩放到合适尺寸。很多人写了一段长文本，发现文字跑到节点外面去了，第一反应是去调节点尺寸，结果没用，因为当前的 Overflow 策略是不处理溢出。这时候把策略改成按宽度换行，或者改成自动缩小，问题立刻解决。先看 Overflow，再看尺寸，最后才看锚点，这个排查顺序能帮你少走很多弯路。

另外，中文字体这块有个坑必须提前说：引擎默认使用的字体，字形覆盖范围有限，显示英文数字没问题，但换到中文时可能显示成方块或者干脆空白。正确做法是在 Label 组件的字体属性上指定一个带中文字形资源的字体文件，或者把它设成使用系统字体。我在浏览器预览里测试中文正常、打包到真机就变方块，就是因为预览时的字体回退走的是系统字体，而运行时环境不一样。只要是中文项目，字体一定要单独确认一遍，别等出包才发现。

3.3 分辨率适配与 Widget 的用法

文字放上去之后，第二个要面对的问题是：不同尺寸的屏幕上，它跑到哪里去了？

Canvas 节点上有一个适配相关的配置，通常可以选择按高度适配、按宽度适配或者两者都适配。按高度适配适合竖屏为主的界面，按宽度适配适合横屏。选错方向的直接后果是，在你的开发机上看着正好，换一台长宽比不同的手机，界面元素就被裁掉或者挤在一起。

对于"我要把一行字固定在屏幕正中间"这种需求，最省事的做法是给节点加一个 Widget 组件。Widget 的直觉是"把节点对齐到父节点的某条边"，你可以选择水平居中和垂直居中，勾选之后节点位置会随着父节点尺寸变化自动重算，不需要你写任何代码。这比手算坐标可靠得多，尤其是在适配多种机型时。

实测下来，新手第一个 Hello World 想达到的效果通常是"无论什么屏幕，文字都在中间且完整可见"，那么组合方案就是：Canvas 的适配策略选一个与你项目主方向一致的，Label 的 Overflow 选择自动换行并按宽度撑高，节点上挂 Widget 做居中。这三步做完，你在绝大多数设备上看到的效果都是一致的。

4. 加一段 TypeScript，让 Hello World 动起来

4.1 组件的生命周期回调执行顺序

光显示一行静态文字，其实还没碰到脚本系统。真正让 Hello World 有意义的一步，是写一个脚本组件，让它在运行时改文字内容、打印日志。这一步会验证"脚本编译链路是通的"，价值比显示那行字本身大得多。

Cocos Creator 3.x 的生命周期回调，常用的有这几个，执行顺序也要记清楚：

• onLoad：节点被激活时调用一次，适合做初始化、取引用。此时节点还没开始渲染，父节点的 onLoad 可能还没执行完，不要在这里依赖兄弟节点的状态。
• onEnable：组件每次被启用时调用，节点被反复启用/禁用时会多次触发。
• start：在当前帧第一次更新前调用一次，适合做需要其他节点已完成初始化的逻辑。
• update(dt)：每帧调用，dt是距离上一帧的秒数，适合做逐帧逻辑。
• lateUpdate(dt)：在 update 之后、渲染前调用，适合做跟随类逻辑，比如相机跟人。
• onDisable/onDestroy：禁用与销毁时调用，用来清理定时器、事件监听。

新手最容易犯的错是在 onLoad 里依赖其他节点的初始化结果。因为节点树的 onLoad 执行顺序是从上到下按层级来的，你在子节点的 onLoad 里访问一个还没执行 onLoad 的兄弟节点，拿到的引用可能是空的，然后报一个看不懂的空指针。稳妥做法是：取引用放 onLoad，用引用干活放 start。

4.2 @property 把编辑器里的资源接到脚本上

3.x 里让编辑器面板暴露一个属性给你的脚本，靠的是装饰器。写法大概是引入引擎模块，然后用@ccclass给类注册一个名字，用@property标注你要暴露的字段。

import { _decorator, Component, Label } from 'cc'; const { ccclass, property } = _decorator; @ccclass('HelloWorld') export class HelloWorld extends Component { @property(Label) label: Label = null; private elapsed: number = 0; start() { if (this.label) { this.label.string = 'Hello World from Cocos Creator'; } } update(dt: number) { this.elapsed += dt; if (this.elapsed >= 1) { this.elapsed = 0; console.log('已经运行了 1 秒'); } } }

这里有几个细节值得展开。第一，@property(Label)里的类型参数决定了属性检查器里显示什么类型的槽位，写Label你就能把场景里的 Label 节点直接拖进去，而不是在代码里写查找节点的路径。能用拖拽绑定的就不要用字符串路径去查找，因为路径一旦改名就会静默失效，而拖拽绑定在资源被删时编辑器会直接报错，问题暴露得更早。

第二，类名建议和脚本文件名保持一致。编辑器在添加组件、序列化数据时都会用到类名，两者对不上时会出现"组件加不上去""重新打开场景后组件丢了"这类问题。这条规则在 3.x 里依然值得遵守，别去试探边界。

第三，@property标注的字段在编辑器里改了值，会覆盖代码里的默认值。这是有意设计的，但新手常被它坑到：代码里把默认值从 1 改成 2，运行结果还是 1，因为编辑器已经把这个属性序列化到场景文件里了。改默认值之前，先确认场景里没有覆盖它，或者在属性检查器里点一下重置。

4.3 脚本挂载不上的几种典型情形

写完脚本，回到编辑器，右键节点添加组件，如果列表里找不到你的脚本，按这个顺序查：

1. 脚本有没有编译错误。看控制台，任何一处类型错误都会导致整个脚本无法注册。
2. 类名和文件名是否一致，不一致时编辑器可能识别不到。
3. @ccclass装饰器的名字有没有重复，同名会冲突，后注册的覆盖前面的。
4. 脚本文件是不是放在了 assets 目录之外，目录外的文件不会被纳入资源系统。
5. 扩展名是否正确，.ts和.js的处理方式不同。

挂载成功之后还有一步验证：在属性检查器里确认那个 Label 槽位确实被赋值了。忘了拖拽赋值是最高频的低级错误，代码写得再对，label是 null，运行时什么都不会发生，控制台还未必有报错——因为你写了判空保护。

4.4 预览与调试的基本姿势

跑预览有两种常用方式，浏览器预览和编辑器内预览。日常改 UI 参数、调位置看效果，用编辑器内预览最快；查逻辑、看网络请求、打断点，用浏览器预览配合开发者工具更合适。

日志打印方面，console.log会输出到控制台面板。日志里带上上下文信息，比如把节点名、关键数值拼进去，而不是只打印一个"进来了"。真机上排查问题时你往往拿不到断点，只能靠日志，所以从第一天就用好日志习惯，收益是长期的。

浏览器预览还有一个好处是可以用性能面板看帧率和绘制调用次数。哪怕只是一个 Hello World，你也可以顺手看一眼：一个 Label 消耗几个绘制调用、有没有异常的帧率波动。这不是小题大做，而是让你从一开始就对"我这个场景大概什么开销"有感觉，将来节点数量上来时才不会失控。

5. 打包成 APK：从构建设置到真机跑起来

5.1 构建原生工程的前置依赖

这一步是 Hello World 之旅里最像"配环境"的部分，因为它确实要装一堆外部的开发工具：Android SDK、NDK、以及 JDK。三者的角色分别是：SDK 提供平台库和构建工具，NDK 提供编译原生代码所需的工具链，JDK 提供构建系统本身运行需要的 Java 环境。

这里有几个容易出问题的点。版本要互相匹配——不同版本的编辑器对 NDK、JDK 版本有各自的要求，装错了通常会报一些和实际原因毫无关系的错误，比如找不到某个编译器、某个中间文件格式不对。稳妥做法是去查你所使用版本的官方环境搭建文档，按文档推荐的版本号装，不要图省事用系统里已有的旧版本。

路径依然不能带中文和空格，并且记得在编辑器的偏好设置里把这三个路径都手动指定一遍。有些安装包会自动写环境变量，有些不会，指定路径比依赖环境变量更可靠。

装完之后建议先做个无关的小验证：在命令行里执行一次构建工具的版本查询命令，能打印出版本号说明路径和环境变量没问题。这比在编辑器里构建失败后再去猜要高效得多。

5.2 构建面板的关键参数逐项说明

构建面板里的参数看着多，真正影响出包成败和运行效果的主要是下面这些。

包名这件事我要多说一句。它看起来只是构建时填的一个字符串，但它是应用在系统里的唯一身份，一旦发布再改就相当于换了个应用，用户数据和评价都带不过去。所以哪怕是练手的 Hello World，也养成用规范反向域名的习惯，比如com.yourname.helloworld这样，别用默认值一路点下去。

ABI 架构的选择也很实际。每多选一个架构，包里就多一份原生库，包体增长非常明显。初期调试只保留当前测试机对应的架构就够了，等要发版再按用户设备分布决定保留哪些。

5.3 生成物目录与 Android Studio 里的操作

构建完成后，产物会输出到build目录下平台对应的子目录里。这个目录里既有可以直接安装的包，也有一个完整的原生工程目录，后者可以用 Android Studio 打开做进一步定制——比如改应用图标、改启动画面、加平台相关的配置。

编辑器里通常还会提供"编译"和"运行"两个操作：编译负责把原生工程编译出安装包，运行负责把它装到你连接的测试设备上并启动。第一次跑建议按"构建、编译、运行"的顺序一步步来，不要跳步，因为每一步失败的原因完全不同：构建失败多半是资源配置问题，编译失败多半是外部依赖和版本问题，运行失败多半是签名或设备连接问题。分步走能让你一眼看出是哪一类。

如果要在 Android Studio 里手动打包，注意签名配置。调试版本可以用默认调试签名，正式发布必须用你自己的签名文件，并且这个文件要妥善保存——丢了就没法给已有的应用发更新。这是很多个人开发者吃过的大亏。

5.4 真机白屏黑屏的排查链路

应用装上去了，一点开是白屏或者黑屏，这是新手最慌的时刻。别急，按下面这条链路走，基本能覆盖八成情况。

第一步，看日志。通过命令行工具抓设备日志，过滤应用包名相关的输出，重点找报错和资源加载失败的记录。很多白屏其实是启动脚本抛了个异常，日志里写得清清楚楚。

第二步，确认是不是资源没打进去。构建时如果有资源被排除，或者某个资源引用了但没被纳入，启动阶段会卡在加载。日志里通常有找不到某个资源标识的记录。

第三步，确认渲染后端与设备兼容。换一个渲染后端重新构建试试，这是排查图形相关白屏最快的二分法。

第四步，确认方向与分辨率。屏幕方向配置和实际设备方向不一致时，可能出现界面渲染在了可视区域之外，看着像白屏，其实是画面跑到别处去了。这种情况在 Hello World 阶段特别常见。

第五步，确认包体完整。传输过程损坏、安装不完整的概率不高但不是零，重新构建安装一次能排除掉这类干扰。

我自己的经验是：能在浏览器预览里跑通的东西，打包出问题九成在环境配置和资源引用上，而不是逻辑代码。所以排查时优先怀疑配置，别一上来就改代码。

6. 新手第一次做 Hello World 最容易踩的坑

把上面散落的经验集中成一张表，方便你对照自查。

这张表里的每一条我都在不同项目里真实遇到过。它们有一个共同特征：现象和原因之间的距离很远，靠猜基本猜不中。所以遇到问题时的正确姿势是先缩小范围——把问题定位到"环境、配置、代码"三类中的哪一类，再往下查。分类对了，接下来只是时间问题。

7. 从这个小工程开始的工程习惯

7.1 目录与命名规范

Hello World 虽然小，但它是一个绝佳的时机去建立目录规范。我的建议是在 assets 下按功能而非按资源类型分目录：脚本、场景、图片、预制体各自有归属，但当项目变大时，按功能切分的目录更抗腐化，因为你找东西时的思维是"这个功能相关的文件在哪"，而不是"所有图片在哪"。

命名上，脚本用大驼峰或者下划线分隔保持统一，场景用清晰的中文或英文描述性名字，资源名避免用new、copy、111这类无语义的名字。这条听起来像强迫症，但等到你需要在一百个资源里定位一个问题时，你会感谢当初的自己。

7.2 版本控制里哪些目录不该提交

前面表格里已经列过，这里再强调一次实践方式：准备一个忽略规则文件，把缓存目录、构建产物、本机配置目录都排除掉。判断标准很简单——如果一个目录删掉之后，工程重新打开能自动重建，那它就不该进版本库。

这样做的直接好处是仓库体积小、克隆快、冲突少。反过来，如果把缓存目录也提交了，多人协作时每个人机器上的缓存内容不同，每次合并都是一堆无意义的冲突，真正重要的代码改动反而被淹没在噪音里。我在早期项目里吃过这个亏，一个仓库因为误提交了缓存目录，体积涨到几百兆，后来清理花了很久。

7.3 把这次的验证结果记录下来

最后一条建议，可能是我这篇文章里最想强调的：把这次 Hello World 跑通用的所有参数都记下来。编辑器版本号、外部工具的版本号、构建面板的关键参数、包名规则、真机测试的机型。写在一个简单的文本文件里，放在工程根目录下，或者团队文档里。

原因很简单：半年后你换了台电脑，或者带了个新人进来，所有参数都要重问一遍。而这份记录能让你在半小时内把环境搭回来，而不是再花一天去踩一遍已经踩过的坑。我自己每个新项目开荒时都会留这么一份文件，它是我从 Hello World 这个阶段带走的最有价值的东西，比那行字本身值钱得多。