前言¶
用 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 不越界做測試。
核心功能¶
- Label 排版規則：四種 Overflow 模式的適用場景，多行文本的正確寫法（
RESIZE_HEIGHT+ LineHeight + 錨點貼邊），解決文字溢出、堆疊、錯位。 - UITransform 錨點語義：錨點與座標的關係，避免節點位置理解錯誤。
- Widget 動態佈局陷阱：尤其是
ALWAYS模式每幀重置佈局的坑。 - 純代碼 UI 構建模板：不用編輯器拖拽，直接用代碼搭節點樹。
- 編譯驗證流程：修改
.ts後的編譯驗證步驟，含編輯器最小化導致編譯不生效的陷阱。 - 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
