前言¶

微信小程序上線後，常見問題往往不是「不會寫頁面」，而是審覈被拒、廣告佔屏、本地數據莫名丟失，或在別人倉庫裏改了一處卻牽出一串框架報錯。通用開發 Skill 多講腳手架與 API，對「第一天就該寫進 app.json 的配置」和「在既有項目裏只改指定功能」的紀律講得少。下面介紹 SkillHub 上的 微信小程序避坑與協作指南（@user_6b038fe4/wechat-miniprogram-guardian），它把生產環境裏的教訓整理成可交給 Agent 執行的指南。

這是什麼¶

微信小程序避坑與協作指南 是面向微信小程序生產項目的 Agent Skill，採用通用 SKILL.md 格式，由 SkillHub 用戶 user_6b038fe4 發佈。官方入口：

• 頁面：https://skillhub.cn/skills/user_6b038fe4/wechat-miniprogram-guardian
• API 路徑：https://api.skillhub.cn/user_6b038fe4/wechat-miniprogram-guardian

在 SkillHub 中分類爲 dev-programming，公開數據爲評分 99778、下載約 900 次（以平臺展示爲準）。

它解決兩類問題：從零搭建時把審覈、廣告、存儲等坑前置到地基；維護已上線小程序時按步驟處理審覈整改、廣告異常、數據丟失與框架報錯，並在他人項目上遵守協作邊界。

核心功能¶

資料與 Skill 簡介一致，能力可概括爲兩條線。

線 A：從零搭建（第一天做對的地基）¶

1. app.json 防坑配置：把易導致審覈或運行問題的全局配置提前寫清，減少後期返工。
2. 本地優先存儲模式：圍繞數據持久化給出可落地的存儲策略，降低「用戶數據保存後丟失」類事故。
3. 雙廣告系統分搭：區分並拆分兩套廣告體系的接入方式，避免廣告佔屏、位異常等線上問題。
4. 審覈合規內置：把提審常見合規要求納入搭建流程，而不是提審前一晚臨時補材料。

線 B：維護與修復已上線項目¶

1. 審覈整改：按被拒原因組織修改與復提思路。
2. 廣告位異常：排查與修復廣告展示、配置類問題。
3. 數據保存丟失：針對存儲與同步鏈路做定位與修復指引。
4. 框架報錯甄別：區分業務代碼與基礎庫/框架層問題，避免誤改。
5. 他人項目改動紀律：在陌生倉庫中控制改動範圍，降低連帶風險。

協作鐵律（Skill 強調的三條）¶

• 先驗證後動手：用日誌、真機或最小復現確認現象，再改代碼。
• 只改指定功能：不借機做大範圍重構。
• 隔離演示：演示、調試與生產邏輯分開，避免污染線上行爲。

安裝與啓用¶

SkillHub 的安裝說明見 https://skillhub.cn/install/skillhub.md。先做 CLI 檢查，再裝到當前 Agent 的 skills 目錄（裝錯目錄會導致 Agent 讀不到技能）。

1、檢查或安裝 SkillHub CLI¶

command -v skillhub && skillhub --version

未安裝時可執行（完整安裝含默認 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

僅 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

2、安裝本 Skill¶

CLI 解析到的包名爲 @user_6b038fe4/wechat-miniprogram-guardian，內部 slug 爲 wechat-miniprogram-guardian。安裝時需用 --dir 指向當前環境的 skills 目錄，例如 Cursor 常用：

skillhub install wechat-miniprogram-guardian --namespace user_6b038fe4 --dir ~/.cursor/skills/

Claude Code 可將 --dir 設爲 ~/.claude/skills/；Codex 可爲 ~/.codex/skills/ 或項目下的 .agents/skills/（以你當前客戶端文檔爲準）。

3、用自然語言讓 Agent 安裝（可選）¶

與同站其他用戶 Skill 的提示方式一致，可將下面話術發給支持 SkillHub 的 Agent：

請根據 https://skillhub.cn/install/skillhub.md，安裝 @user_6b038fe4/wechat-miniprogram-guardian。

安裝後按客戶端要求刷新或重啓，使 SKILL.md 被加載。若 skillhub install 下載失敗，先到 SkillHub 頁面確認技能是否仍上架，再重試或聯繫發佈者。

典型用法¶

本 Skill 無單獨腳本入口，用法是 在對話中描述場景，由 Agent 按 SKILL.md 中的檢查清單與步驟推進。下列表述與 Skill 自述的觸發條件一致，可直接複用。

新建小程序

我要從零做一個微信小程序，請按微信小程序避坑與協作指南：先幫我列 app.json 防坑項、本地優先存儲和廣告分搭方案，並帶上審覈合規檢查點。

審覈被拒

小程序提審被拒，駁回理由是 [粘貼微信後臺原文]。請按避坑指南走審覈整改，只改與駁回相關的內容，並說明需要我自測的項。

廣告或數據問題

線上廣告位異常 / 用戶反饋數據保存後丟失。請先列驗證步驟再改代碼，按 Skill 區分是配置、存儲還是框架問題。

在他人項目上改動

這是別人的小程序倉庫，我只允許改 [具體功能]。請遵守先驗證後動手、只改指定功能、隔離演示，改動前先說明影響範圍。

經過上面的步驟，Agent 應優先引用 Skill 內的規範，而不是隨意擴 scope。

適用場景與注意¶

適合誰

• 準備上線或已上線、需要 生產級 紀律的微信小程序開發者。
• 用 Cursor、Claude Code、Codex 等帶 Skills 的 Agent 寫小程序、排線上問題時，希望有一套固定的避坑與協作話術。

建議在以下情況啓用

• 新建小程序、審覈被拒、廣告位異常、數據保存丟失、莫名框架報錯、在他人項目上做功能修改。

注意

• 本文功能描述來自 SkillHub 公開簡介與安裝 CLI 解析結果；具體配置字段、代碼片段以安裝後的 SKILL.md 爲準，本文不替代官方技能正文。
• 微信小程序平臺規則與基礎庫會更新，涉及提審、隱私、廣告政策時仍需對照 微信開放文檔 最新說明。
• 官方 API 頁面若返回 405 或安裝下載 404，以 SkillHub 網頁 skillhub.cn/skills/user_6b038fe4/wechat-miniprogram-guardian 的狀態爲準。

結尾¶

微信小程序避坑與協作指南 把「審覈、廣告、存儲、協作邊界」從零散經驗收成一條 Agent 可執行的線：新建時打地基，維護時少誤傷。若你正在做生產向的小程序，可在 SkillHub 打開官方頁查看詳情並安裝：https://skillhub.cn/skills/user_6b038fe4/wechat-miniprogram-guardian。