微信小程序基础设施与合规备案技能。当用户要初始化小程序项目、配置云开发环境、部署云函数、创建数据库集合、处理小程序常见错误码、配置页面分享、或需要做ICP备案和隐私合规时使用。覆盖从项目骨架搭建到合规上线的完整基础设施流程。AI 按本规范生成项目骨架与配置,用户按检查清单验收。From its SKILL.md
npx -y skills add aixiaoxiang/xx-skills --skill wechatAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 19 stars19 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
20.7 KB, as published. Nobody here has run it
基础设施与合规备案
先把地基打好,再盖房子。基础设施不对,后面全是返工。
这个技能做什么
帮你在项目启动阶段一次性搞定三件事:
- 项目骨架 — 标准目录结构、配置文件、云开发环境
- 云能力 — 云函数部署、数据库集合、数据传递策略
- 合规备案 — ICP 备案、隐私保护指引、UGC 声明
跳过任何一步,后期都会踩坑。最常见的教训:没做备案就提交审核,被打回;云函数没调超时,AI 接口 3 秒超时报错。
读者说明: 本 skill 主要给 AI 执行规范(生成目录、配置、云函数模板),次要给人判断标准(检查清单验收)。用户不需要自己敲配置,只需要会描述项目类型、能看懂报错截图反馈给 AI。
贯穿案例:小象取色(摄像头取色 → AI 中式命名 → 配色海报 → 历史记录)。
一、项目初始化
1.1 标准目录结构
AI 参考实现(小象取色项目骨架):
miniprogram-project/
├── miniprogram/ # 小程序前端代码
│ ├── pages/ # 页面
│ │ ├── picker/ # 取色页(核心)
│ │ │ ├── picker.wxml
│ │ │ ├── picker.wxss
│ │ │ ├── picker.js
│ │ │ └── picker.json
│ │ ├── poster/ # 海报生成页
│ │ └── history/ # 颜色历史页
│ ├── components/ # 自定义组件
│ ├── utils/ # 工具函数
│ │ └── util.js
│ ├── config/ # 配置
│ │ ├── cloud.js # 云环境配置
│ │ └── theme.js # 主题 Token(见 xx-brand)
│ ├── app.js # 应用入口
│ ├── app.json # 应用配置
│ ├── app.wxss # 全局样式
│ └── sitemap.json
├── cloudfunctions/ # 云函数
│ └── aiNameColor/ # AI 取色命名
│ ├── index.js
│ ├── package.json
│ └── config.json
├── project.config.json # 项目配置
└── README.md
AI 执行约束: 目录结构必须按上述分层,pages 按功能拆分,config 集中管理配置,禁止把配置写死在页面 js 里。
1.2 project.config.json
AI 参考实现:
{
"miniprogramRoot": "miniprogram/",
"cloudfunctionRoot": "cloudfunctions/",
"setting": {
"urlCheck": true,
"es6": true,
"enhance": true,
"postcss": true,
"preloadBackgroundData": false,
"minified": true,
"newFeature": false,
"coverView": true,
"nodeModules": false,
"autoAudits": false,
"showShadowRootInWxmlPanel": true,
"scopeDataCheck": false,
"uglifyFileName": false,
"checkInvalidKey": true,
"checkSiteMap": true,
"uploadWithSourceMap": true,
"compileHotReLoad": false,
"useMultiFrameRuntime": true,
"useApiHook": true,
"useApiHostProcess": true,
"babelSetting": {
"ignore": [],
"disablePlugins": [],
"outputPath": ""
},
"enableEngineNative": false,
"useIsolateContext": true,
"userConfirmedBundleSwitch": false,
"packNpmManually": false,
"packNpmRelationList": [],
"minifyWXSS": true,
"disableUseStrict": false,
"minifyWXML": true,
"showES6CompileOption": false,
"useCompilerPlugins": false
},
"appid": "替换为你的AppID",
"projectname": "xiaoxiang-color",
"libVersion": "3.5.0",
"condition": {},
"editorSetting": {
"tabIndent": "insertSpaces",
"tabSize": 2
}
}
AI 执行约束: appid 必须替换为用户真实 AppID,不能留占位符上线。
1.3 app.json 基础配置
AI 参考实现(小象取色):
{
"pages": [
"pages/picker/picker",
"pages/poster/poster",
"pages/history/history"
],
"window": {
"backgroundTextStyle": "light",
"navigationBarBackgroundColor": "#8B0000",
"navigationBarTitleText": "小象取色",
"navigationBarTextStyle": "white",
"backgroundColor": "#F2F2F7"
},
"style": "v2",
"sitemapLocation": "sitemap.json",
"lazyCodeLoading": "requiredComponents",
"permission": {
"scope.camera": {
"desc": "用于摄像头实时取色"
},
"scope.writePhotosAlbum": {
"desc": "用于保存配色海报到相册"
}
}
}
lazyCodeLoading设为requiredComponents可按需注入组件代码,减少启动耗时。
AI 执行约束: permission 里声明的 scope 必须与实际使用的 API 一一对应,多声明会被审核打回;每条 desc 必须写清用途。
二、云开发环境
2.1 wx.cloud.init 配置
AI 参考实现(app.js):
App({
globalData: {
userInfo: null,
cloudEnv: 'your-env-id'
},
onLaunch() {
if (!wx.cloud) {
console.error('请使用 2.2.3 或以上的基础库以使用云能力')
return
}
wx.cloud.init({
env: this.globalData.cloudEnv,
traceUser: true
})
}
})
2.2 环境ID配置
关键原则:环境ID只在一处定义,其他地方引用,不硬编码。
AI 参考实现(config/cloud.js):
const CLOUD_ENV = 'your-env-id'
module.exports = {
CLOUD_ENV,
COLLECTIONS: {
COLORS: 'colors',
POSTERS: 'posters',
FEEDBACK: 'feedback'
}
}
const { CLOUD_ENV } = require('../config/cloud')
const db = wx.cloud.database({ env: CLOUD_ENV })
判断标准(给人): 全项目搜 your-env-id 应该只出现在 config/cloud.js 一处。出现多处 = 不合格。
2.3 多环境管理(可选)
AI 参考实现:
const ENV_MAP = {
develop: 'dev-env-id',
trial: 'trial-env-id',
release: 'prod-env-id'
}
const envVersion = __wxConfig.envVersion
const CLOUD_ENV = ENV_MAP[envVersion] || ENV_MAP.release
三、云函数部署
3.1 云函数标准结构
cloudfunctions/
└── aiNameColor/
├── index.js # 入口
├── package.json # 依赖声明(必需)
└── config.json # 云函数配置(可选)
3.2 package.json(必需)
每次新增依赖或修改 package.json 后,必须重新上传并部署(云端安装依赖)。
{
"name": "aiNameColor",
"version": "1.0.0",
"description": "AI 中式颜色命名",
"main": "index.js",
"dependencies": {
"wx-server-sdk": "~2.6.3"
}
}
常见坑:本地
npm install了但没上传node_modules,或者改了package.json没点"上传并部署:云端安装依赖"。两者都会导致require报错MODULE_NOT_FOUND。
3.3 云函数入口模板
AI 参考实现:
const cloud = require('wx-server-sdk')
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV })
exports.main = async (event, context) => {
const { action, data } = event
try {
switch (action) {
case 'getName':
return await handleGetName(data)
case 'getScheme':
return await handleGetScheme(data)
default:
return { code: 400, message: '未知操作' }
}
} catch (err) {
console.error('云函数错误:', err)
return { code: 500, message: err.message }
}
}
async function handleGetName(data) {
const db = cloud.database()
const result = await db.collection('colors')
.where({ _openid: '{openid}' })
.orderBy('createdAt', 'desc')
.limit(20)
.get()
return { code: 0, data: result.data }
}
3.4 上传部署步骤
- 右键云函数文件夹 → "上传并部署:云端安装依赖"
- 等待上传完成(控制台会显示日志)
- 在云开发控制台 → 云函数 → 测试
3.5 超时调整(重要)
AI 相关云函数默认 3 秒超时,调用大模型必超时。
调整方法:
- 云开发控制台 → 云函数 → 选择函数 → 配置 → 超时时间 → 改为 60 秒
- 或在
config.json中配置:
{
"permissions": {
"openapi": []
},
"timeout": 60
}
必须调整超时的场景:调用大模型API、图片处理、批量数据库操作、文件上传处理。建议统一设为 60 秒。
AI 执行约束: 任何调用 AI 模型的云函数,超时必须显式设为 60 秒,不能留默认 3 秒。
四、数据库
4.1 集合创建
在云开发控制台 → 数据库 → 创建集合(小象取色示例):
| 集合名 | 用途 | 权限设置 |
|---|---|---|
colors | 用户取色历史 | 仅创建者可读写 |
posters | 生成的海报记录 | 仅创建者可读写 |
feedback | 用户反馈 | 仅创建者可读写 |
权限说明:
仅创建者可读写— 默认推荐,用户只能操作自己的数据所有用户可读,仅创建者可写— 排行榜等公开数据仅管理端可读写— 敏感配置数据
4.2 数据库操作模板
AI 参考实现:
const addResult = await db.collection('colors').add({
data: {
hex: '#8B0000',
name: '故宫红',
createdAt: db.serverDate(),
status: 1
}
})
const queryResult = await db.collection('colors')
.where({ _openid: '{openid}' })
.orderBy('createdAt', 'desc')
.limit(20)
.get()
const updateResult = await db.collection('colors')
.doc(recordId)
.update({ data: { status: 0 } })
const deleteResult = await db.collection('colors')
.doc(recordId)
.remove()
AI 执行约束: 时间字段必须用 db.serverDate(),不能用前端 new Date()(用户时区/改机时间不可信)。
4.3 数据传递优化
核心原则:能在前端传参的,不要让云函数再去数据库查一遍。
❌ 慢:前端 → 云函数 → 查数据库取用户信息 → 调用API → 返回
✅ 快:前端已有用户信息 → 直接传给云函数 → 调用API → 返回
AI 参考实现(反例 vs 正例):
exports.main = async (event, context) => {
const user = await db.collection('users')
.where({ _openid: event.openid }).get()
const result = await callAI(event.input, user.data[0].preference)
return result
}
exports.main = async (event, context) => {
const result = await callAI(event.input, event.preference)
return result
}
URL 传参优于数据库读取的场景:
- 列表页 → 详情页:直接传 id 和必要字段,详情页用 id 查详情
- 用户信息:登录后缓存到 globalData,传参使用
- 临时数据:不需要持久化的中间状态,用页面栈或 URL 传递
wx.navigateTo({
url: `/pages/poster/poster?id=${item._id}&hex=${encodeURIComponent(item.hex)}`
})
onLoad(options) {
const { id, hex } = options
this.setData({ hex })
this.loadDetail(id)
}
判断标准(给人): 列表点进详情,详情页加载要 < 500ms。如果慢,检查是不是云函数多查了一次数据库。
五、常见错误码速查表
| 错误码 | 含义 | 原因 | 解决方案 |
|---|---|---|---|
-604100 | 云函数调用失败 | 云函数未部署/超时/代码报错 | 检查云函数是否上传部署;超时则调至60秒;查看云函数日志 |
-502005 | 数据库权限不足 | 集合权限设置不允许当前操作 | 控制台修改集合权限为"仅创建者可读写" |
-504003 | 数据库记录不存在 | 查询的 doc id 不存在 | 检查 id 是否正确;先判断记录是否存在 |
-10009 | 系统错误 | 基础库版本过低或系统异常 | 升级基础库版本;重启微信开发者工具 |
ERR_FILE_NOT_FOUND | 文件未找到 | 云存储文件路径错误或文件已删除 | 检查 cloudPath;确认文件已上传 |
错误处理统一封装(AI 参考实现):
function handleError(err, context = '') {
console.error(`[${context}] 错误:`, err)
const errorMap = {
'-604100': '服务繁忙,请稍后重试',
'-502005': '操作权限不足',
'-504003': '数据不存在',
'-10009': '系统异常,请更新微信',
'ERR_FILE_NOT_FOUND': '文件不存在'
}
const message = errorMap[err.errCode] || err.errMsg || '未知错误,请稍后重试'
wx.showToast({ title: message, icon: 'none' })
return { success: false, message }
}
module.exports = { handleError }
AI 执行约束: 返回给用户的错误提示不能含技术细节(堆栈、key 片段、SQL),只能给友好文案;技术细节只进日志。
六、页面分享规范
所有页面必须定义 onShareAppMessage 和 onShareTimeline,否则用户无法分享。
AI 参考实现:
Page({
onShareAppMessage() {
return {
title: '小象取色 - 一键取中式色名',
path: '/pages/picker/picker',
imageUrl: '/assets/share-cover.png'
}
},
onShareTimeline() {
return {
title: '小象取色 - 一键取中式色名',
query: 'from=timeline',
imageUrl: '/assets/share-cover.png'
}
}
})
不定义
onShareAppMessage的页面,右上角菜单的"转发"按钮会灰色不可点。 不定义onShareTimeline的页面,无法分享到朋友圈。
AI 执行约束: 分享标题不超过 20 字;分享封面图必须是 5:4 比例。
七、文件编辑安全规范
追加方法前必须检查文件是否已闭合(} 或 ])。
这是最常见的破坏性操作:在已有文件末尾追加代码时,如果原文件最后一个字符不是闭合符号,追加会导致语法错误。
安全追加检查清单
追加前检查:
1. 读取目标文件完整内容
2. 确认最后一个字符是 } 或 ](对象/数组闭合)
3. 如果最后一个字符是 } → 追加新方法需要先加逗号
4. 如果文件为空 → 从头写,不需要逗号
5. 追加后验证语法正确性
AI 执行约束: 改任何 .js / .json / .wxml 文件前,先 Read 完整内容,确认结构闭合,再做修改。永远不要假设文件末尾的状态。
八、ICP 备案
8.1 主体类型选择
| 类型 | 适用场景 | 所需材料 | 审核时间 |
|---|---|---|---|
| 个人主体 | 个人开发者、自媒体 | 身份证、人脸识别 | 7-20个工作日 |
| 企业主体 | 公司、个体工商户 | 营业执照、法人身份证、公章 | 7-20个工作日 |
选择建议:
- 如果小程序涉及支付、经营性内容 → 必须企业主体
- 如果只是工具类、无收费 → 个人主体即可
- 企业主体审核更严格但功能权限更多
判断标准(给人): 小象取色要做付费配色/海报模板 → 涉及经营性内容 → 必须企业主体。
8.2 隐私保护指引填写
关键原则:不勾选"自定义",只声明微信API实际获取的信息。
在 mp.weixin.qq.com → 设置 → 服务内容声明 → 用户隐私保护指引:
填写步骤:
- 不要勾选"自定义信息"
- 根据实际使用的 API 勾选对应的信息类型:
| 使用的微信API | 对应信息项 |
|---|---|
wx.getUserProfile | 微信昵称、头像 |
wx.getLocation | 位置信息 |
<camera> 取色 | 相机 |
wx.saveImageToPhotosAlbum | 相册(写入) |
wx.getPhoneNumber | 手机号 |
| 云开发数据库存储 | 不算用户信息 |
- 填写信息用途说明(小象取色示例):
- 相机:用于实时取色
- 相册:用于保存生成的配色海报
- 第三方信息共享声明(如果用了第三方 SDK/API):
- 本程序使用了 混元大模型 进行 颜色命名,
会将您的 取色色值 传输至 腾讯云 用于 生成中式色名。
常见坑:勾选了未实际使用的信息项,审核会被打回。只勾选真实用到的。
AI 执行约束: 隐私指引里声明的信息项必须与代码里实际调用的 API 完全一致,多声明或少声明都会被审核打回。
8.3 UGC 声明
用户输入文本/图片不算 UGC,但用户发布的内容被其他用户看到才算。
| 场景 | 是否UGC | 需要声明 |
|---|---|---|
| 用户取色结果仅自己看 | ❌ 不是 | 不需要 |
| 用户保存海报到相册 | ❌ 不是 | 不需要 |
| 用户发布配色被其他用户看到 | ✅ 是 | 需要 |
| 用户评论/评分其他人可见 | ✅ 是 | 需要 |
如果产品包含 UGC,需要在备案中声明:
UGC内容安全管理:
1. 用户发布内容前需同意内容规范
2. 系统对UGC内容进行关键词过滤
3. 提供举报入口,收到举报后24小时内处理
4. 违规内容予以删除,严重违规者封禁账号
判断标准(给人): 小象取色 MVP 不做社区 → 不需要 UGC 声明;后期加社区 → 必须补声明。
8.4 备案流程
1. 准备材料
├─ 个人:身份证正反面照片、人脸识别
└─ 企业:营业执照、法人身份证、网站负责人信息
2. 提交备案
└─ mp.weixin.qq.com → 设置 → 基本设置 → ICP备案
3. 等待审核
├─ 小程序平台初审(1-3个工作日)
├─ 通信管理局审核(7-20个工作日)
└─ 审核结果通过短信和站内信通知
4. 备案通过后
└─ 在小程序"关于"页面展示备案号
8.5 备案号展示
备案通过后,必须在小程序中展示备案号:
AI 参考实现:
<view class="about-footer">
<view class="icp-info">
<text>备案号:</text>
<text class="icp-number" bindtap="copyIcp">{{icpNumber}}</text>
</view>
</view>
Page({
data: {
icpNumber: '京ICP备XXXXXXXX号-X'
},
copyIcp() {
wx.setClipboardData({
data: this.data.icpNumber,
success: () => {
wx.showToast({ title: '已复制备案号', icon: 'success' })
}
})
}
})
AI 执行约束: 备案号必须真实,不能用占位符上线;展示位置必须在用户可见的"关于"页。
九、开发检查清单
在提交审核前,逐项检查:
基础设施
-
project.config.json中appid已替换为真实 AppID - 云开发环境ID已配置且在
config/cloud.js中统一管理 -
wx.cloud.init在app.js中正确调用 - 所有云函数已上传部署(含
package.json依赖) - AI相关云函数超时已调整为 60 秒
- 数据库集合已创建,权限设置正确
代码规范
- 所有页面定义了
onShareAppMessage和onShareTimeline - 分享标题不超过20字,分享封面图5:4比例
- 错误处理使用统一封装(
errorHandler) - 数据传递优先用URL参数,减少不必要的数据库查询
- 修改文件前已确认文件闭合状态
合规备案
- ICP备案已通过,备案号已展示
- 隐私保护指引已填写(只勾选实际使用的API对应信息)
- 未勾选"自定义信息"
- 第三方信息共享已声明(如有)
- UGC声明已填写(如有社区/评论功能)
- UGC内容审核机制已实现(如有)
上线前
- 基础库版本 ≥ 2.2.3
-
lazyCodeLoading已开启 -
sitemap.json已配置 - 体验版已完整测试通过
AI 执行约束: 任一项未通过不能提交审核。备案类项目未完成不能上线。
使用方式
当你需要搭建小程序基础设施时,告诉我你的项目类型,我来生成项目骨架和配置。
对话示例:
- "我要做小象取色这个小程序,帮我搭项目结构" → 我生成标准目录 + app.json + 云函数模板
- "云函数调用报 -604100 错误" → 我帮你排查是没部署还是超时
- "小象取色要做 ICP 备案,需要准备什么" → 我帮你梳理材料和流程
- "用户反馈分享按钮点不了" → 检查是否定义了 onShareAppMessage
与其他技能的关系
- 前置: xx-prd 定义功能规格(项目骨架的页面来源)
- 并行: xx-brand 主题 Token(config/theme.js)、xx-blocks 组件库(components/)
- 下游: xx-ai 云函数里调混元、xx-backend key 管理与缓存
- 安全交汇: xx-safety 的隐私授权、生成式 AI 备案(基础设施层落地)
方法论来源
- 微信小程序官方文档 — 云开发、基础能力、备案规范
- 微信开放平台备案指南 — ICP备案操作规范
- 个人信息保护法 — 隐私保护指引填写依据
- 云开发最佳实践 — 数据传递与性能优化策略