uniapp 小程序开发规范 Skill：20 条红线 + 8 份详解文档

用 AI 写 uniapp 小程序，最怕的就是 10 个页面 10 种写法、变量名乱起、颜色硬编码满天飞。这个 Skill 用 8 份规范文档 + 20 条红线规则，把 AI 约束在一套标准里干活，代码质量和维护效率直接拉满。

什么是规范？简单说就是一套标准流程——一个萝卜一个坑，这里填 A 那里填 B，让维护人员和 AI 一看就懂。规范设计和 UI 设计（主题、组件化、页面模板）本质上是一回事：一开始就让 AI 在一块制定好的范围里干活，不可越雷池半步。

因为越到后期，没有规范的项目 AI 维护成本越大、token 消耗越多、效率越低。AI 确实能自主学习，即使项目乱七八糟也能找到关键词修 bug，但代价巨大：幻觉和失忆概率直线上升、修复提示词越来越长、token 烧得飞快。而提前定好规范，AI 会"嗅到"你的规范并按它办事。

一、为什么需要规范

让 AI 直接开发当然能搞出一套像模像样的 uniapp 项目（比如用骨架生成 Skill），但骨架里的血肉——结构和规范——如果不约束，后期维护会很痛苦：

用 AI 写代码尤其明显，因为 AI 的幻觉和失忆特性：变量名乱起（aaa、temp、data1）、颜色硬编码（#666、#999）、尺寸不统一（20rpx、24rpx、28rpx 混用）、接口写法各异。这时候就需要一个规范 Skill 来约束 AI。

二、8 个维度

这个 Skill 的核心是提供 8 份详细规范文档，覆盖一个 uniapp 项目的整个过程。

1. api-architecture.md — 请求封装：统一请求前缀、统一错误提示、统一 401 跳转、统一管理 user 状态。接好后端的第一步。

2. store-guide.md — Pinia 状态管理：用户状态等需要动态管理的数据，用 defineStore 声明，computed 派生登录态。

3. router-guide.md — 路由配置与守卫：封装 router.push，路由守卫自动处理登录拦截。

4. performance.md — 性能优化：DOM 节点限制（页面 ≤ 1000 个）、setData 限制（单次 ≤ 100KB、频率 ≤ 20 次/秒）、长列表必须分页。

5. storage-guide.md — 存储 Key 常量：禁止硬编码 storage key，统一收口到 STORAGE_KEYS 常量，退出登录时一并清除。

6. analytics.md — 埋点规范：统一的 analytics.pageView / analytics.click 接口，收集用户行为。

7. component-communication.md — 组件通信：props/emit（父→子）、provide/inject（祖先→后代）、EventBus（兄弟组件）三种场景的标准化用法。

8. 20 条红线规则：违反任意一条就是不合规（部分示例）：

三、标准目录结构

这套常用的 uniapp 项目结构，可以用骨架生成 Skill 生成，重要的是上面 8 个维度要在目录里有体现：

src/
├── api/            # 接口封装（request.ts + _mocks_）
├── components/     # 公共组件
├── pages/          # 业务页面
├── stores/         # Pinia 状态管理
├── utils/          # 工具函数（router.ts/analytics.ts/storage.ts）
├── config/         # 应用配置
├── constants/      # 常量（STORAGE_KEYS）
├── styles/         # SCSS 样式系统
├── App.vue         # 根组件
└── pages.json      # 页面路由

四、使用方式

仓库地址：https://github.com/jiushiwon/wg-skills/tree/main/uniapp-standard-skill

触发命令：

/uniapp-standard-skill 你能干啥

或者直接描述需求，比如「uniapp 开发规范」「小程序规范」「接口怎么写」。

实战中可以让它按规范整理项目，比如：

/uniapp-standard-skill 帮我按照 storage 规范来整理项目，所有常量统一管理起来

小结

uniapp-standard-skill 解决的问题：10 个页面 10 种写法 → 统一目录结构和编码规范；AI 写代码放飞自我 → 20 条红线约束；接口写法各异 → 8 份文档详细指导；代码审查凭感觉 → 对照红线有理有据。

这就是 VibeCoding 的魅力：先定规范，再让 AI 干活。建议项目开始前必看，做到一半也能用。