前言¶

用 Cocos Creator 3.8.x 做 UI，最常见的翻车现场是：Label 文字溢出或叠在一起、多行文本高度不对、拖了 Widget 反而位置乱了、改完 .ts 保存没生效、节点渲染顺序莫名其妙。这些 bug 大多不是引擎的问题，而是对 Label 排版、锚点语义、Widget 布局这几个机制理解不到位。

下面介绍的这个 Skill——Cocos UI 开发防坑指南——就是把这些容易踩的坑整理成可执行的规则，覆盖从写 UI 到验证编译的完整流程。

这是什么¶

一句话定位：一份面向 Cocos Creator 3.8.x 的 UI 开发实践与防坑指南，把常见的错误写法和对应的正确写法、排查路径固定下来。

• 坐标：@user_4edac78e/cocos-dev-guide
• 版本：1.0.1
• 来源：community（社区）
• 分类：dev-programming
• 标签：requires_api_key=false（无需 API Key）
• 发布者：user_4edac78e
• 数据（来自 SkillHub 页面）：评分 100000，下载 1234 次

它解决的只是一件事：写对代码。项目搭建、离线校验、场景序列化交给 cocos-project-scaffold；浏览器预览自动化测试和报告交给 cocos-preview-bsk-test。三者互补，本 Skill 不越界做测试。

核心功能¶

1. Label 排版规则：四种 Overflow 模式的适用场景，多行文本的正确写法（RESIZE_HEIGHT + LineHeight + 锚点贴边），解决文字溢出、堆叠、错位。
2. UITransform 锚点语义：锚点与坐标的关系，避免节点位置理解错误。
3. Widget 动态布局陷阱：尤其是 ALWAYS 模式每帧重置布局的坑。
4. 纯代码 UI 构建模板：不用编辑器拖拽，直接用代码搭节点树。
5. 编译验证流程：修改 .ts 后的编译验证步骤，含编辑器最小化导致编译不生效的陷阱。
6. bug 症状→根因→修复模板：按症状查根因，按根因找修复。

安装与启用¶

SkillHub 页面未给出安装命令，只提供地址：

https://www.skillhub.cn/skills/user_4edac78e/cocos-dev-guide

该 Skill 基于通用 SKILL.md 格式。在支持 Skill 的客户端（如 Cursor、Claude Code、Codex 等）中，将 skill 目录放入对应的 skills 目录后，由模型按 SKILL.md 中的触发条件启用即可。页面没有提供各客户端的具体配置差异，这里不展开。

典型用法¶

Skill 的触发场景写得很明确：当你正在用 Cocos Creator 3.8.x 开发游戏，需要写或改 UI（Label、UITransform、锚点、布局、纯代码构建节点），或者排查文字溢出、堆叠、错位、渲染顺序、编译不生效等问题时使用。

以最典型的多行文本为例，Skill 给出的规则可以还原为：

// 多行文本正确写法的三个要素
label.overflow = Label.Overflow.RESIZE_HEIGHT; // 高度随文本增长
label.lineHeight = 40;                         // 行高显式设置
// 锚点贴边，避免内容从节点中心溢出

再比如编译验证流程，Skill 强调的不是”保存”而是验证编译确实发生：

// 1. 保存修改
// 2. 确认编辑器窗口处于激活状态（最小化时编译会被跳过）
// 3. 触发一次编译并确认无报错

修改 .ts 后如果没生效，先按上面三步排查，而不是反复改代码。

适用场景与注意¶

适合谁：正在用 Cocos Creator 3.8.x 写 UI 的开发者，尤其是从其他引擎转过来、或习惯纯代码构建节点的人。

限制和坑：

• 只覆盖 3.8.x，其他版本的行为可能不同，不要套用。
• 只管写对代码，测试、构建、预览不在范围内。
• Widget 的 ALWAYS 模式每帧重置布局，动态布局时容易出意外，Skill 中有专门的说明。
• Bug 修复模板是按症状反查根因，遇到没见过的症状时，先用模板过一遍再动手。

结尾¶

这个 Skill 的价值不在于教你 Cocos 的 API，而是把 UI 开发中反复出现的错误固化成规则，让你少在同一类坑里摔几次。如果你正在 3.8.x 上做 UI，值得在写第一个 Label 之前看一遍。

官方地址：https://www.skillhub.cn/skills/user_4edac78e/cocos-dev-guide