66 KiB
66 KiB
小程序管理技能 v3.0
📅 创建日期：2026-01-25 📅 更新日期：2026-01-25（v3.0 全能版） 📋 通过微信开放平台API完整管理小程序的全生命周期：申请、认证、开发、审核、发布、运营 🚀 支持多小程序管理、一键部署、自动认证检查、汇总报告
🎯 能力全景图
╔══════════════════════════════════════════════════════════════════════════════╗
║ 小程序管理技能 v3.0 能力全景图 ║
╠══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
║ │ 🔧 工具整合层 │ ║
║ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ ║
║ │ │ 微信开发者 │ │ miniprogram │ │ 开放平台 │ │ GitHub │ │ ║
║ │ │ 工具 CLI │ │ -ci (npm) │ │ API │ │ Actions │ │ ║
║ │ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │ ║
║ └─────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
║ │ 📦 核心功能层 │ ║
║ │ │ ║
║ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ ║
║ │ │ 多小程序 │ │ 项目 │ │ 一键 │ │ 汇总 │ │ ║
║ │ │ 管理 │ │ 检查 │ │ 部署 │ │ 报告 │ │ ║
║ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ ║
║ │ │ ║
║ └─────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
║ │ 🚀 部署流程 │ ║
║ │ │ ║
║ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ ║
║ │ │ 检查 │ → │ 编译 │ → │ 上传 │ → │ 提审 │ → │ 审核 │ → │ 发布 │ │ ║
║ │ │check │ │build │ │upload│ │audit │ │wait │ │release│ │ ║
║ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ ║
║ │ │ │ │ │ │ │ │ ║
║ │ ▼ ▼ ▼ ▼ ▼ ▼ │ ║
║ │ 自动化 自动化 自动化 自动化 等待 手动/自动 │ ║
║ │ 1-7天 │ ║
║ └─────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
📊 命令速查表
| 命令 | 说明 | 示例 |
|---|---|---|
mp_full.py report |
生成所有小程序汇总报告 | python3 mp_full.py report |
mp_full.py check |
检查项目问题 | python3 mp_full.py check soul-party |
mp_full.py auto |
全自动部署（上传+提审） | python3 mp_full.py auto soul-party |
mp_deploy.py list |
列出所有小程序 | python3 mp_deploy.py list |
mp_deploy.py add |
添加新小程序 | python3 mp_deploy.py add |
mp_deploy.py cert-status |
查询认证状态 | python3 mp_deploy.py cert-status soul-party |
mp_deploy.py cert-done |
标记认证完成 | python3 mp_deploy.py cert-done soul-party |
mp_deploy.py release |
发布上线 | python3 mp_deploy.py release soul-party |
🎯 技能概述
本技能用于通过API实现微信小程序的完整管理，包括：
核心能力
| 阶段 | 能力 | 说明 |
|---|---|---|
| 申请 | 快速注册小程序 | 复用公众号主体资质，无需300元认证费 |
| 认证 | 企业认证管理 | 自动检查认证状态、提醒过期、材料管理 |
| 配置 | 基础信息设置 | 名称、头像、介绍、类目管理 |
| 开发 | 代码管理 | 上传代码、生成体验版 |
| 审核 | 提审发布 | 提交审核、查询状态、撤回、发布 |
| 运营 | 接口管理 | 域名配置、隐私协议、接口权限 |
| 推广 | 小程序码 | 生成无限量小程序码 |
| 数据 | 数据分析 | 访问数据、用户画像 |
v2.0 新增能力
| 能力 | 命令 | 说明 |
|---|---|---|
| 多小程序管理 | mp_deploy.py list |
统一管理多个小程序 |
| 一键部署 | mp_deploy.py deploy <id> |
编译→上传→提审一步完成 |
| 认证管理 | mp_deploy.py cert <id> |
认证状态检查、材料管理 |
| 快速上传 | mp_deploy.py upload <id> |
快速上传代码到开发版 |
开源工具集成
| 工具 | 用途 | 安装方式 |
|---|---|---|
| miniprogram-ci | 微信官方CI工具 | npm install miniprogram-ci -g |
| 微信开发者工具CLI | 本地编译上传 | 安装开发者工具自带 |
| multi-mini-ci | 多平台小程序上传 | GitHub开源 |
🚀 触发词
- 管理小程序
- 小程序申请
- 小程序审核
- 小程序发布
- 上传小程序代码
- 配置小程序域名
- 生成小程序码
- 查看小程序状态
🏗️ 技术架构
管理方式对比
| 方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 微信后台手动操作 | 无需开发 | 效率低，无法批量 | 单个小程序 |
| 微信开发者工具CLI | 简单易用 | 功能有限 | 开发测试 |
| 开放平台API（本方案） | 功能完整、可自动化 | 需要开发 | 批量管理、自动化 |
整体架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 小程序管理引擎 v1.0 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 第一层：认证层 │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ 第三方平台 │ │ component_ │ │ authorizer_ │ │ │
│ │ │ 认证信息 │ → │ access_token │ → │ access_token │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 第二层：管理API层 │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ 注册 │ │ 配置 │ │ 代码 │ │ 审核 │ │ 运营 │ │ │
│ │ │ 管理 │ │ 管理 │ │ 管理 │ │ 管理 │ │ 管理 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 第三层：本地CLI层 │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ mp_manager.py │ │ 微信开发者 │ │ 自动化脚本 │ │ │
│ │ │ Python CLI │ │ 工具 CLI │ │ Shell │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
📋 前置条件
1. 微信开放平台账号
- 注册地址：https://open.weixin.qq.com/
- 完成开发者资质认证（需企业资质）
2. 创建第三方平台
登录开放平台后台 → 管理中心 → 第三方平台 → 创建
必填信息：
- 平台名称
- 服务类型（选择"平台型"可管理多个小程序）
- 授权发起页域名
- 消息与事件接收URL
3. 获取关键凭证
| 凭证 | 说明 | 获取方式 |
|---|---|---|
component_appid |
第三方平台AppID | 开放平台后台 |
component_appsecret |
第三方平台密钥 | 开放平台后台 |
component_verify_ticket |
验证票据 | 微信每10分钟推送 |
component_access_token |
平台调用凭证 | API获取，2小时有效 |
authorizer_access_token |
授权方调用凭证 | API获取，2小时有效 |
🔑 认证流程
获取 component_access_token
# POST https://api.weixin.qq.com/cgi-bin/component/api_component_token
{
"component_appid": "你的第三方平台AppID",
"component_appsecret": "你的第三方平台密钥",
"component_verify_ticket": "微信推送的验证票据"
}
# 返回
{
"component_access_token": "xxxx",
"expires_in": 7200
}
获取预授权码
# POST https://api.weixin.qq.com/cgi-bin/component/api_create_preauthcode
{
"component_appid": "你的第三方平台AppID"
}
# 返回
{
"pre_auth_code": "xxxx",
"expires_in": 600
}
引导用户授权
https://mp.weixin.qq.com/cgi-bin/componentloginpage?
component_appid=第三方平台AppID&
pre_auth_code=预授权码&
redirect_uri=授权回调地址&
auth_type=1 # 1=仅小程序，2=仅公众号，3=两者都可
获取 authorizer_access_token
# POST https://api.weixin.qq.com/cgi-bin/component/api_query_auth
{
"component_appid": "第三方平台AppID",
"authorization_code": "授权回调返回的code"
}
# 返回
{
"authorization_info": {
"authorizer_appid": "授权方AppID",
"authorizer_access_token": "授权方调用凭证",
"expires_in": 7200,
"authorizer_refresh_token": "刷新令牌"
}
}
📱 核心API接口
一、小程序注册
1.1 复用公众号资质快速注册
前提：已有认证的公众号
# POST https://api.weixin.qq.com/cgi-bin/account/fastregister?access_token=ACCESS_TOKEN
{
"ticket": "公众号扫码授权的ticket"
}
# 返回
{
"errcode": 0,
"errmsg": "ok",
"appid": "新注册的小程序AppID",
"authorization_code": "授权码"
}
优势：
- 无需重新提交主体材料
- 无需对公打款
- 无需支付300元认证费
限制：
- 非个体户：每月可注册5个
- 个体户：每月可注册1个
1.2 快速注册企业小程序
前提：有企业营业执照
# POST https://api.weixin.qq.com/cgi-bin/component/fastregisterminiprogram
{
"name": "小程序名称",
"code": "统一社会信用代码",
"code_type": 1, # 1=营业执照
"legal_persona_wechat": "法人微信号",
"legal_persona_name": "法人姓名",
"component_phone": "联系电话"
}
二、基础信息配置
2.1 获取基础信息
# POST https://api.weixin.qq.com/cgi-bin/account/getaccountbasicinfo
# 无请求参数
# 返回
{
"appid": "小程序AppID",
"account_type": 2, # 2=小程序
"principal_type": 1, # 1=企业
"principal_name": "主体名称",
"realname_status": 1, # 1=已认证
"nickname": "小程序名称",
"head_image_url": "头像URL",
"signature": "简介"
}
2.2 修改名称
# POST https://api.weixin.qq.com/wxa/setnickname?access_token=ACCESS_TOKEN
{
"nick_name": "新名称",
"id_card": "管理员身份证号",
"license": "营业执照media_id", # 需要先上传
"naming_other_stuff_1": "其他证明material_id" # 可选
}
2.3 修改头像
# POST https://api.weixin.qq.com/cgi-bin/account/modifyheadimage?access_token=ACCESS_TOKEN
{
"head_img_media_id": "头像图片media_id", # 需要先上传
"x1": 0, "y1": 0, "x2": 1, "y2": 1 # 裁剪区域
}
2.4 修改简介
# POST https://api.weixin.qq.com/cgi-bin/account/modifysignature?access_token=ACCESS_TOKEN
{
"signature": "新的简介内容" # 4-120字
}
三、类目管理
3.1 获取可选类目
# GET https://api.weixin.qq.com/cgi-bin/wxopen/getallcategories?access_token=ACCESS_TOKEN
3.2 获取已设置类目
# GET https://api.weixin.qq.com/cgi-bin/wxopen/getcategory?access_token=ACCESS_TOKEN
3.3 添加类目
# POST https://api.weixin.qq.com/cgi-bin/wxopen/addcategory?access_token=ACCESS_TOKEN
{
"categories": [
{
"first": 1, # 一级类目ID
"second": 2, # 二级类目ID
"certicates": [ # 资质证明
{"key": "资质名称", "value": "media_id"}
]
}
]
}
3.4 删除类目
# POST https://api.weixin.qq.com/cgi-bin/wxopen/deletecategory?access_token=ACCESS_TOKEN
{
"first": 1,
"second": 2
}
四、域名配置
4.1 设置服务器域名
# POST https://api.weixin.qq.com/wxa/modify_domain?access_token=ACCESS_TOKEN
{
"action": "set", # add/delete/set/get
"requestdomain": ["https://api.example.com"],
"wsrequestdomain": ["wss://ws.example.com"],
"uploaddomain": ["https://upload.example.com"],
"downloaddomain": ["https://download.example.com"],
"udpdomain": ["udp://udp.example.com"],
"tcpdomain": ["tcp://tcp.example.com"]
}
4.2 设置业务域名
# POST https://api.weixin.qq.com/wxa/setwebviewdomain?access_token=ACCESS_TOKEN
{
"action": "set", # add/delete/set/get
"webviewdomain": ["https://web.example.com"]
}
五、隐私协议配置
5.1 获取隐私协议设置
# POST https://api.weixin.qq.com/cgi-bin/component/getprivacysetting?access_token=ACCESS_TOKEN
{
"privacy_ver": 2 # 1=当前版本，2=开发版本
}
5.2 设置隐私协议
# POST https://api.weixin.qq.com/cgi-bin/component/setprivacysetting?access_token=ACCESS_TOKEN
{
"privacy_ver": 2,
"setting_list": [
{
"privacy_key": "UserInfo",
"privacy_text": "用于展示用户头像和昵称"
},
{
"privacy_key": "Location",
"privacy_text": "用于获取您的位置信息以推荐附近服务"
},
{
"privacy_key": "PhoneNumber",
"privacy_text": "用于登录验证和订单通知"
}
],
"owner_setting": {
"contact_email": "contact@example.com",
"contact_phone": "15880802661",
"notice_method": "弹窗提示"
}
}
常用隐私字段：
| privacy_key | 说明 |
|---|---|
UserInfo |
用户信息（头像、昵称） |
Location |
地理位置 |
PhoneNumber |
手机号 |
Album |
相册 |
Camera |
相机 |
Record |
麦克风 |
Clipboard |
剪切板 |
MessageFile |
微信消息中的文件 |
ChooseAddress |
收货地址 |
BluetoothInfo |
蓝牙 |
六、代码管理
6.1 上传代码
# POST https://api.weixin.qq.com/wxa/commit?access_token=ACCESS_TOKEN
{
"template_id": 1, # 代码模板ID
"ext_json": "{\"extAppid\":\"授权方AppID\",\"ext\":{}}",
"user_version": "1.0.0",
"user_desc": "版本描述"
}
注意：需要先在第三方平台创建代码模板
6.2 获取体验版二维码
# GET https://api.weixin.qq.com/wxa/get_qrcode?access_token=ACCESS_TOKEN&path=pages/index/index
# 返回二维码图片
6.3 获取已上传的代码页面列表
# GET https://api.weixin.qq.com/wxa/get_page?access_token=ACCESS_TOKEN
# 返回
{
"errcode": 0,
"page_list": ["pages/index/index", "pages/my/my"]
}
七、审核管理
7.1 提交审核
# POST https://api.weixin.qq.com/wxa/submit_audit?access_token=ACCESS_TOKEN
{
"item_list": [
{
"address": "pages/index/index",
"tag": "电子书 阅读 创业",
"first_class": "教育",
"second_class": "在线教育",
"first_id": 1,
"second_id": 2,
"title": "首页"
}
],
"preview_info": {
"video_id_list": [],
"pic_id_list": []
},
"version_desc": "版本说明",
"feedback_info": "反馈内容",
"feedback_stuff": "media_id" # 反馈附件
}
7.2 查询审核状态
# POST https://api.weixin.qq.com/wxa/get_auditstatus?access_token=ACCESS_TOKEN
{
"auditid": 1234567890
}
# 返回
{
"errcode": 0,
"status": 0, # 0=审核成功，1=审核被拒，2=审核中，3=已撤回，4=审核延后
"reason": "拒绝原因", # status=1时返回
"screenshot": "截图"
}
7.3 查询最新审核状态
# GET https://api.weixin.qq.com/wxa/get_latest_auditstatus?access_token=ACCESS_TOKEN
7.4 撤回审核
# GET https://api.weixin.qq.com/wxa/undocodeaudit?access_token=ACCESS_TOKEN
限制：单个小程序每天只能撤回1次
八、发布管理
8.1 发布已审核通过的版本
# POST https://api.weixin.qq.com/wxa/release?access_token=ACCESS_TOKEN
{} # 无请求参数
# 返回
{
"errcode": 0,
"errmsg": "ok"
}
8.2 版本回退
# GET https://api.weixin.qq.com/wxa/revertcoderelease?access_token=ACCESS_TOKEN
限制：只能回退到上一个版本，且只能回退一次
8.3 获取可回退版本历史
# GET https://api.weixin.qq.com/wxa/revertcoderelease?access_token=ACCESS_TOKEN&action=get_history_version
8.4 分阶段发布
# POST https://api.weixin.qq.com/wxa/grayrelease?access_token=ACCESS_TOKEN
{
"gray_percentage": 10 # 灰度比例 1-100
}
九、小程序码生成
9.1 获取小程序码（有限制）
# POST https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN
{
"path": "pages/index/index?scene=123",
"width": 430,
"auto_color": false,
"line_color": {"r": 0, "g": 0, "b": 0},
"is_hyaline": false # 是否透明背景
}
# 返回图片二进制
限制：每个path只能生成10万个
9.2 获取无限小程序码（推荐）
# POST https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN
{
"scene": "user_id=123&from=share", # 最长32字符
"page": "pages/index/index", # 必须是已发布的页面
"width": 430,
"auto_color": false,
"line_color": {"r": 0, "g": 0, "b": 0},
"is_hyaline": false
}
# 返回图片二进制
注意：scene参数需要在小程序中用onLoad(options)解析
9.3 生成小程序短链接
# POST https://api.weixin.qq.com/wxa/genwxashortlink?access_token=ACCESS_TOKEN
{
"page_url": "pages/index/index?id=123",
"page_title": "页面标题",
"is_permanent": false # 是否永久有效
}
# 返回
{
"errcode": 0,
"link": "https://wxaurl.cn/xxxx"
}
十、接口权限管理
10.1 查询接口调用额度
# POST https://api.weixin.qq.com/cgi-bin/openapi/quota/get?access_token=ACCESS_TOKEN
{
"cgi_path": "/wxa/getwxacode"
}
# 返回
{
"quota": {
"daily_limit": 100000,
"used": 500,
"remain": 99500
}
}
10.2 重置接口调用次数
# POST https://api.weixin.qq.com/cgi-bin/clear_quota?access_token=ACCESS_TOKEN
{
"appid": "小程序AppID"
}
限制：每月只能重置10次
十一、数据分析
11.1 获取访问趋势
# POST https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend?access_token=ACCESS_TOKEN
{
"begin_date": "20260101",
"end_date": "20260125"
}
# 返回
{
"list": [
{
"ref_date": "20260125",
"session_cnt": 1000, # 打开次数
"visit_pv": 5000, # 访问次数
"visit_uv": 800, # 访问人数
"visit_uv_new": 100, # 新用户数
"stay_time_uv": 120.5, # 人均停留时长（秒）
"stay_time_session": 60.2 # 次均停留时长（秒）
}
]
}
11.2 获取用户画像
# POST https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait?access_token=ACCESS_TOKEN
{
"begin_date": "20260101",
"end_date": "20260125"
}
🛠️ 快速使用
方式一：使用Python管理脚本（推荐）
# 进入脚本目录
cd /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/小程序管理/scripts
# 安装依赖
pip install httpx python-dotenv
# 配置凭证
cp .env.example .env
# 编辑 .env 填入你的凭证
# 使用命令行工具
python mp_manager.py status # 查看小程序状态
python mp_manager.py audit # 查看审核状态
python mp_manager.py release # 发布上线
python mp_manager.py qrcode # 生成小程序码
方式二：使用微信开发者工具CLI
# CLI路径
CLI="/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
# 打开项目
$CLI -o "/path/to/miniprogram"
# 编译
$CLI build-npm --project "/path/to/miniprogram"
# 预览（生成二维码）
$CLI preview --project "/path/to/miniprogram" --qr-format image --qr-output preview.png
# 上传代码
$CLI upload --project "/path/to/miniprogram" --version "1.0.0" --desc "版本说明"
# 提交审核
$CLI submit-audit --project "/path/to/miniprogram"
方式三：直接调用API
import httpx
# 配置
ACCESS_TOKEN = "你的access_token"
BASE_URL = "https://api.weixin.qq.com"
async def check_audit_status(auditid: int):
"""查询审核状态"""
async with httpx.AsyncClient() as client:
resp = await client.post(
f"{BASE_URL}/wxa/get_auditstatus?access_token={ACCESS_TOKEN}",
json={"auditid": auditid}
)
return resp.json()
# 使用
result = await check_audit_status(1234567890)
print(result)
📁 文件结构
小程序管理/
├── SKILL.md # 技能说明文档（本文件）
├── scripts/
│ ├── mp_manager.py # 小程序管理CLI工具
│ ├── mp_api.py # API封装类
│ ├── requirements.txt # Python依赖
│ └── .env.example # 环境变量模板
└── references/
├── API接口速查表.md # 常用API速查
├── 隐私协议填写指南.md # 隐私协议配置指南
└── 审核规范.md # 审核常见问题
⚠️ 常见问题
Q1: 如何获取 component_verify_ticket？
微信会每10分钟向你配置的"消息与事件接收URL"推送。你需要部署一个服务来接收并存储它。
# 接收推送示例
@app.post("/callback")
async def receive_ticket(request: Request):
xml_data = await request.body()
# 解密并解析XML
# 提取 ComponentVerifyTicket
# 存储到Redis或数据库
return "success"
Q2: 审核被拒常见原因？
| 原因 | 解决方案 |
|---|---|
| 类目不符 | 确保小程序功能与所选类目一致 |
| 隐私协议缺失 | 配置完整的隐私保护指引 |
| 诱导分享 | 移除"分享到群获取xx"等诱导文案 |
| 虚拟支付 | iOS不能使用虚拟支付，需走IAP |
| 内容违规 | 检查文案、图片是否合规 |
| 功能不完整 | 确保所有页面功能正常 |
Q3: 审核需要多长时间？
- 首次提审：1-7个工作日
- 非首次：1-3个工作日
- 加急审核：付费服务，24小时内
Q4: 如何提高审核通过率？
- 提交完整测试账号：如需登录才能体验功能
- 录制操作视频：复杂功能建议附上操作视频
- 详细的版本描述：说明本次更新内容
- 完善隐私协议：所有收集数据的接口都要说明用途
Q5: 代码模板是什么？
第三方平台需要先将小程序代码上传到"草稿箱"，再添加到"代码模板库"。之后可以用这个模板批量部署到多个小程序。
流程：开发完成 → 上传到草稿箱 → 添加到模板库 → 使用模板部署
🔗 官方文档
📊 当前项目配置
Soul派对小程序
| 项目 | 配置值 |
|---|---|
| AppID | wxb8bbb2b10dec74aa |
| 项目路径 | /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram |
| API域名 | https://soul.quwanzhi.com |
| 当前版本 | 1.0.13 |
| 认证状态 | ⏳ 审核中（等待1-5工作日） |
| 检查结果 | ✅ 8项通过 / ⚠️ 2项警告 / ❌ 0项错误 |
| 可上传 | ✅ 是 |
| 可发布 | ❌ 需等待认证通过 |
快速命令
# 打开项目
/Applications/wechatwebdevtools.app/Contents/MacOS/cli -o "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram"
# 预览
/Applications/wechatwebdevtools.app/Contents/MacOS/cli preview --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" --qr-format image --qr-output preview.png
# 上传
/Applications/wechatwebdevtools.app/Contents/MacOS/cli upload --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" --version "1.0.0" --desc "版本说明"
🚀 全自动部署流程（v3.0）
完整生命周期流程图
╔══════════════════════════════════════════════════════════════════════════════╗
║ 小程序完整生命周期管理 ║
╠══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ 阶段一：准备阶段 ║
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
║ │ │ 注册小程序│ → │ 企业认证 │ → │ 配置项目 │ │ ║
║ │ │ (微信后台)│ │ (300元/年)│ │ (添加到管理)│ │ ║
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
║ │ │ │ │ │ ║
║ │ │ │ ▼ │ ║
║ │ │ │ mp_deploy.py add │ ║
║ │ │ ▼ │ ║
║ │ │ 等待审核 1-5 天 │ ║
║ │ │ mp_deploy.py cert-done │ ║
║ │ │ ║
║ └─────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ 阶段二：开发阶段 ║
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
║ │ │ 编写代码 │ → │ 本地测试 │ → │ 项目检查 │ │ ║
║ │ │ (开发者) │ │ (模拟器) │ │ mp_full │ │ ║
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
║ │ │ │ ║
║ │ ▼ │ ║
║ │ mp_full.py check <id> │ ║
║ │ 检查: 配置/域名/隐私/认证 │ ║
║ │ │ ║
║ └─────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ 阶段三：部署阶段（全自动） ║
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ mp_full.py auto <id> -v "1.0.0" -d "版本描述" │ ║
║ │ │ │ ║
║ │ ▼ │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
║ │ │ ① 检查 │ → │ ② 上传 │ → │ ③ 提审 │ │ ║
║ │ │ 项目问题 │ │ 代码到微信│ │ 提交审核 │ │ ║
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
║ │ │ │ │ │ ║
║ │ ▼ ▼ ▼ │ ║
║ │ 自动检测 使用CLI/npm 已认证→API提审 │ ║
║ │ 配置/认证/域名 优先级选择 未认证→手动提审 │ ║
║ │ │ ║
║ └─────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ 阶段四：发布阶段 ║
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
║ │ │ 等待审核 │ → │ 审核通过 │ → │ 发布上线 │ │ ║
║ │ │ 1-7工作日 │ │ 通知 │ │ release │ │ ║
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
║ │ │ │ ║
║ │ ▼ │ ║
║ │ mp_deploy.py release <id> │ ║
║ │ 或 微信后台点击发布 │ ║
║ │ │ ║
║ └─────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ 阶段五：运营阶段 ║
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
║ │ │ 数据分析 │ │ 汇总报告 │ │ 版本迭代 │ │ ║
║ │ │ mp_manager│ │ mp_full │ │ 循环部署 │ │ ║
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
║ │ │ │ │ │ ║
║ │ ▼ ▼ ▼ │ ║
║ │ data命令 report命令 返回部署阶段 │ ║
║ │ │ ║
║ └─────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
工具整合架构图
┌────────────────────────────────────────────────────────────────────────────┐
│ 小程序管理工具整合架构 │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 用户命令层 │ │
│ │ mp_full.py report │ mp_full.py check │ mp_full.py auto │ │
│ │ mp_deploy.py list │ mp_deploy.py cert │ mp_manager.py status │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Python 管理层 │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ mp_full.py │ │ mp_deploy.py │ │ mp_api.py │ │ │
│ │ │ 全能管理器 │ │ 部署工具 │ │ API封装 │ │ │
│ │ │ • 检查 │ │ • 多小程序 │ │ • 认证 │ │ │
│ │ │ • 报告 │ │ • 认证管理 │ │ • 审核 │ │ │
│ │ │ • 自动部署 │ │ • 发布 │ │ • 发布 │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 外部工具层 │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ 微信开发者 │ │ miniprogram │ │ 微信开放平台 │ │ │
│ │ │ 工具 CLI │ │ -ci (npm) │ │ API │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • 打开项目 │ │ • 上传代码 │ │ • 提交审核 │ │ │
│ │ │ • 预览 │ │ • 预览 │ │ • 发布 │ │ │
│ │ │ • 上传 │ │ • 构建npm │ │ • 认证管理 │ │ │
│ │ │ • 编译 │ │ • sourceMap │ │ • 数据分析 │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ 优先级: 1 优先级: 2 优先级: 3 │ │
│ │ (无需密钥) (需要密钥) (需要token) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────┘
快速开始
# 进入脚本目录
cd /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/小程序管理/scripts
# 1. 查看已配置的小程序
python3 mp_deploy.py list
# 2. 添加新小程序（交互式）
python3 mp_deploy.py add
# 3. 检查认证状态
python3 mp_deploy.py cert-status soul-party
# 4. 一键部署
python3 mp_deploy.py deploy soul-party
# 5. 审核通过后发布
python3 mp_deploy.py release soul-party
命令速查
| 命令 | 说明 | 示例 |
|---|---|---|
list |
列出所有小程序 | python3 mp_deploy.py list |
add |
添加新小程序 | python3 mp_deploy.py add |
deploy |
一键部署 | python3 mp_deploy.py deploy soul-party |
upload |
仅上传代码 | python3 mp_deploy.py upload soul-party |
cert |
提交认证 | python3 mp_deploy.py cert soul-party |
cert-status |
查询认证状态 | python3 mp_deploy.py cert-status soul-party |
cert-done |
标记认证完成 | python3 mp_deploy.py cert-done soul-party |
release |
发布上线 | python3 mp_deploy.py release soul-party |
📋 企业认证详解
认证流程图
┌──────────────────────────────────────────────────────────────┐
│ 企业认证流程 │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 准备 │ → │ 提交 │ → │ 审核 │ │
│ │ 材料 │ │ 认证 │ │ 等待 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │ │
│ ↓ ↓ ↓ │
│ ┌─────────────────────────────────────────┐ │
│ │ • 营业执照 • 微信后台上传 • 1-5工作日 │ │
│ │ • 法人身份证 • 法人扫码验证 • 审核结果 │ │
│ │ • 法人微信号 • 支付300元 • 通知 │ │
│ └─────────────────────────────────────────┘ │
│ │
│ ⚠️ 认证有效期：1年，到期需年审 │
│ │
└──────────────────────────────────────────────────────────────┘
认证材料清单
| 材料 | 必需 | 说明 |
|---|---|---|
| 企业营业执照 | ✅ | 扫描件或照片，信息清晰 |
| 法人身份证 | ✅ | 正反面照片 |
| 法人微信号 | ✅ | 需绑定银行卡，用于扫码验证 |
| 联系人手机号 | ✅ | 接收审核通知 |
| 认证费用 | ✅ | 300元/年 |
| 其他资质 | 可选 | 特殊行业需要（如医疗、金融） |
认证状态说明
| 状态 | 说明 | 下一步操作 |
|---|---|---|
unknown |
未知/未检查 | 运行 cert-status 检查 |
pending |
审核中 | 等待1-5个工作日 |
verified |
已认证 | 可以正常发布 |
rejected |
被拒绝 | 查看原因，修改后重新提交 |
expired |
已过期 | 需要重新认证（年审） |
认证API（第三方平台）
如果你有第三方平台资质，可以通过API代商家提交认证：
# POST https://api.weixin.qq.com/wxa/sec/wxaauth?access_token=ACCESS_TOKEN
{
"auth_type": 1, # 1=企业
"auth_data": {
"name": "企业名称",
"code": "统一社会信用代码",
"legal_persona_wechat": "法人微信号",
"legal_persona_name": "法人姓名",
"legal_persona_idcard": "法人身份证号",
"component_phone": "联系电话"
}
}
🔧 GitHub开源工具推荐
1. miniprogram-ci（官方）
微信官方提供的CI工具，支持Node.js环境使用。
安装：
npm install miniprogram-ci -g
使用：
const ci = require('miniprogram-ci');
const project = new ci.Project({
appid: 'wxb8bbb2b10dec74aa',
type: 'miniProgram',
projectPath: '/path/to/miniprogram',
privateKeyPath: '/path/to/private.key',
ignores: ['node_modules/**/*']
});
// 上传
await ci.upload({
project,
version: '1.0.0',
desc: '版本描述',
setting: {
es6: true,
minify: true
}
});
获取私钥：
- 登录小程序后台
- 开发管理 → 开发设置
- 小程序代码上传密钥 → 下载
2. multi-mini-ci
多平台小程序自动化上传工具。
GitHub: https://github.com/Ethan-zjc/multi-mini-ci
支持平台：
- 微信小程序
- 支付宝小程序
- 百度小程序
- 字节跳动小程序
3. GitHub Actions集成
在项目中创建 .github/workflows/deploy.yml：
name: Deploy MiniProgram
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm install
- name: Build
run: npm run build
- name: Upload to WeChat
env:
PRIVATE_KEY: ${{ secrets.MINIPROGRAM_PRIVATE_KEY }}
run: |
echo "$PRIVATE_KEY" > private.key
npx miniprogram-ci upload \
--pp ./dist \
--pkp ./private.key \
--appid wxb8bbb2b10dec74aa \
--uv "1.0.${{ github.run_number }}" \
-r 1 \
--desc "CI auto deploy"
📁 完整文件结构（v3.0）
小程序管理/
├── SKILL.md # 技能说明文档（本文件）
├── scripts/
│ ├── mp_full.py # 全能管理工具（推荐）⭐
│ ├── mp_deploy.py # 部署工具（多小程序管理）
│ ├── mp_manager.py # API管理工具（基础版）
│ ├── mp_api.py # API封装类（Python SDK）
│ ├── apps_config.json # 多小程序配置文件
│ ├── requirements.txt # Python依赖
│ ├── env_template.txt # 环境变量模板
│ └── reports/ # 检查报告存放目录
│ ├── summary_*.json # 汇总报告
│ └── report_*.json # 项目报告
└── references/
├── API接口速查表.md # 常用API速查
├── 企业认证完整指南.md # 认证操作指南
├── 隐私协议填写指南.md # 隐私协议配置指南
└── 审核规范.md # 审核常见问题
脚本功能对比
| 脚本 | 功能 | 推荐场景 |
|---|---|---|
| mp_full.py | 全能：检查+报告+自动部署 | 日常管理（推荐） |
| mp_deploy.py | 多小程序管理+认证 | 多项目管理 |
| mp_manager.py | API调用工具 | 高级操作 |
| mp_api.py | Python SDK | 二次开发 |
📊 多小程序配置
配置文件位于 scripts/apps_config.json：
{
"apps": [
{
"id": "soul-party",
"name": "Soul派对",
"appid": "wxb8bbb2b10dec74aa",
"project_path": "/path/to/miniprogram",
"certification": {
"status": "verified",
"enterprise_name": "厦门智群网络科技有限公司"
}
},
{
"id": "another-app",
"name": "另一个小程序",
"appid": "wx1234567890",
"project_path": "/path/to/another",
"certification": {
"status": "pending"
}
}
],
"certification_materials": {
"enterprise_name": "厦门智群网络科技有限公司",
"license_number": "统一社会信用代码",
"legal_persona_name": "法人姓名",
"component_phone": "15880802661"
}
}
⚡ 常见场景速查
场景1：发布时提示"未完成微信认证"
# 1. 检查认证状态
python3 mp_deploy.py cert-status soul-party
# 2. 如果未认证，查看认证指引
python3 mp_deploy.py cert soul-party
# 3. 在微信后台完成认证后，标记完成
python3 mp_deploy.py cert-done soul-party
# 4. 重新部署
python3 mp_deploy.py deploy soul-party
场景2：新建小程序并快速上线
# 1. 添加小程序配置
python3 mp_deploy.py add
# 2. 提交认证
python3 mp_deploy.py cert my-new-app
# 3. 在微信后台完成认证（1-5天）
# 4. 认证通过后标记
python3 mp_deploy.py cert-done my-new-app
# 5. 一键部署
python3 mp_deploy.py deploy my-new-app
# 6. 审核通过后发布
python3 mp_deploy.py release my-new-app
场景3：仅更新代码（不提审）
# 快速上传到开发版
python3 mp_deploy.py upload soul-party -v "1.0.5" -d "修复xxx问题"
场景4：批量管理多个小程序
# 查看所有小程序
python3 mp_deploy.py list
# 检查所有认证状态
for app in soul-party another-app third-app; do
echo "=== $app ==="
python3 mp_deploy.py cert-status $app
done
🔗 相关资源
官方文档
开源项目
- miniprogram-ci - 官方CI工具
- multi-mini-ci - 多平台上传
- uz-miniprogram-ci - 一键上传发布
相关文章
🔥 实战经验库（持续更新）
基于 Soul创业派对 项目开发过程中的真实问题和解决方案
一、数据库与后端问题
1.1 后台初始化失败：Unknown column 'password' in 'field list'
问题现象：后台用户管理显示"初始化失败"
根本原因：数据库表结构缺少字段
解决方案：创建数据库初始化API自动修复
// app/api/db/init/route.ts
// 自动检查并添加缺失字段
const columnsToAdd = [
{ name: 'password', type: 'VARCHAR(100)' },
{ name: 'session_key', type: 'VARCHAR(100)' },
{ name: 'referred_by', type: 'VARCHAR(50)' },
{ name: 'is_admin', type: 'BOOLEAN DEFAULT FALSE' },
]
for (const col of columnsToAdd) {
// 检查列是否存在，不存在则添加
await query(`ALTER TABLE users ADD COLUMN ${col.name} ${col.type}`)
}
访问修复：curl https://your-domain.com/api/db/init
1.2 Column 'open_id' cannot be null
问题现象：后台添加用户失败
根本原因：数据库 open_id 字段设置为 NOT NULL，但后台添加用户时没有openId
解决方案：
ALTER TABLE users MODIFY COLUMN open_id VARCHAR(100) NULL
最佳实践：openId允许为NULL，因为：
- 后台手动添加的用户没有openId
- 微信登录用户有openId
- 两种用户需要共存
1.3 AppID配置不一致
问题现象：微信登录返回错误，或获取openId失败
根本原因：项目中多个文件使用了不同的AppID
检查清单：
| 文件 | 配置项 | 正确值 |
|---|---|---|
miniprogram/project.config.json |
appid | wxb8bbb2b10dec74aa |
app/api/miniprogram/login/route.ts |
MINIPROGRAM_CONFIG.appId | wxb8bbb2b10dec74aa |
app/api/wechat/login/route.ts |
APPID | wxb8bbb2b10dec74aa |
app/api/withdraw/route.ts |
WECHAT_PAY_CONFIG.appId | wxb8bbb2b10dec74aa |
搜索命令：
# 查找所有AppID配置
rg "wx[a-f0-9]{16}" --type ts --type json
1.4 用户ID设计最佳实践
推荐方案：使用 openId 作为用户主键
// 微信登录创建用户
const userId = openId // 直接使用openId作为用户ID
await query(`
INSERT INTO users (id, open_id, ...) VALUES (?, ?, ...)
`, [userId, openId, ...])
优势：
- 与微信官方标识一致
- 便于追踪和管理
- 后台显示更直观
兼容方案：后台添加的用户使用 user_ 前缀
二、前端与UI问题
2.1 Next.js Hydration错误
问题现象：页面显示"哎呀，出错了"，控制台报 hydration 错误
根本原因：服务端和客户端渲染结果不一致（如使用localStorage、zustand持久化）
解决方案：添加mounted状态检查
export default function AdminLayout({ children }) {
const [mounted, setMounted] = useState(false)
useEffect(() => {
setMounted(true)
}, [])
// 等待客户端mount后再渲染
if (!mounted) {
return <div>加载中...</div>
}
return <div>{children}</div>
}
2.2 数据类型不匹配：toFixed() 报错
问题现象：显示金额时报错 toFixed is not a function
根本原因：数据库返回的 DECIMAL 字段是字符串类型
解决方案：
// ❌ 错误
<div>{user.earnings.toFixed(2)}</div>
// ✅ 正确
<div>{parseFloat(String(user.earnings || 0)).toFixed(2)}</div>
通用处理函数：
const formatMoney = (value: any) => {
return parseFloat(String(value || 0)).toFixed(2)
}
三、小程序开发问题
3.1 搜索功能：章节ID格式不一致
问题现象：搜索结果跳转到阅读页404
根本原因：
book-chapters.json使用chapter-2,chapter-3格式- 阅读页使用
1.1,1.2格式
解决方案：从标题提取章节号
// 从标题提取章节号（如 "1.1 荷包：..." → "1.1"）
const sectionIdMatch = chapter.title?.match(/^(\d+\.\d+)\s/)
const sectionId = sectionIdMatch ? sectionIdMatch[1] : chapter.id
3.2 搜索功能：敏感信息过滤
需求：搜索结果不能显示用户手机号、微信号等
实现：
const cleanContent = content
.replace(/1[3-9]\d{9}/g, '***') // 手机号
.replace(/微信[：:]\s*\S+/g, '微信：***') // 微信号
.replace(/QQ[：:]\s*\d+/g, 'QQ：***') // QQ号
.replace(/邮箱[：:]\s*\S+@\S+/g, '邮箱：***') // 邮箱
3.3 上下章导航：付费内容也需要显示
需求：即使用户没有购买，也要显示上一篇/下一篇导航
实现：将导航组件移到付费墙之外
<!-- 付费墙 -->
<view class="paywall">
<!-- 解锁按钮 -->
</view>
<!-- 章节导航 - 始终显示 -->
<view class="chapter-nav">
<view class="nav-btn nav-prev" bindtap="goToPrev">上一篇</view>
<view class="nav-btn nav-next" bindtap="goToNext">下一篇</view>
</view>
3.4 分销绑定：推广码捕获
需求：用户通过分享链接进入时，自动绑定推广者
实现流程：
// app.js - onLaunch/onShow
onLaunch(options) {
if (options.query && options.query.ref) {
wx.setStorageSync('referral_code', options.query.ref)
this.bindReferral(options.query.ref)
}
}
// 小程序码scene参数解析
const scene = decodeURIComponent(options.scene)
const params = new URLSearchParams(scene)
const ref = params.get('ref')
后端绑定：
UPDATE users SET referred_by = ? WHERE id = ? AND referred_by IS NULL
四、后台管理优化
4.1 菜单精简原则
优化前（9项）：
- 数据概览、网站配置、内容管理、用户管理、匹配配置、分销管理、支付配置、分账提现、二维码、系统设置
优化后（6项）：
- 数据概览、内容管理、用户管理、分账管理、支付设置、系统设置
精简原则：
- 合并相似功能（分销管理 + 分账提现 → 分账管理）
- 移除低频功能（二维码、匹配配置 → 可在系统设置中配置）
- 核心功能优先
4.2 用户绑定关系展示
需求：查看用户的推广下线详情
实现API：
// GET /api/db/users/referrals?userId=xxx
const referrals = await query(`
SELECT * FROM users WHERE referred_by = ?
ORDER BY created_at DESC
`, [referralCode])
展示信息：
- 绑定总数、已付费人数、免费用户
- 累计收益、待提现金额
- 每个绑定用户的状态（VIP/已付费/未付费）
五、分销与提现
5.1 自动分账规则
| 配置项 | 值 | 说明 |
|---|---|---|
| 分销比例 | 90% | 推广者获得订单金额的90% |
| 结算方式 | 自动 | 用户付款后立即计入推广者账户 |
| 提现方式 | 微信零钱 | 企业付款到零钱 |
| 提现门槛 | 1元 | 累计收益≥1元可提现 |
5.2 提现流程
用户申请提现
↓
扣除账户余额，增加待提现金额
↓
管理员后台审核
↓
批准 → 调用微信企业付款API → 到账
拒绝 → 返还用户余额
六、开发规范
6.1 配置统一管理
// lib/config.ts
export const WECHAT_CONFIG = {
appId: process.env.WECHAT_APPID || 'wxb8bbb2b10dec74aa',
appSecret: process.env.WECHAT_APPSECRET || '...',
mchId: '1318592501',
apiKey: '...'
}
所有API文件统一引用此配置，避免硬编码
6.2 数据库字段命名
| 前端字段 | 数据库字段 | 说明 |
|---|---|---|
| openId | open_id | 微信openId |
| hasFullBook | has_full_book | 是否购买全书 |
| referralCode | referral_code | 推广码 |
| pendingEarnings | pending_earnings | 待提现收益 |
规则：数据库使用snake_case，前端使用camelCase
6.3 错误处理模板
export async function POST(request: Request) {
try {
const body = await request.json()
// 业务逻辑
return NextResponse.json({ success: true, data: ... })
} catch (error) {
console.error('[API名称] 错误:', error)
return NextResponse.json({
success: false,
error: '用户友好的错误信息'
}, { status: 500 })
}
}
📌 问题排查清单
小程序无法登录
- 检查AppID是否正确（project.config.json vs 后端）
- 检查AppSecret是否正确
- 检查API域名是否已配置
- 检查后端服务是否正常运行
- 查看后端日志
[MiniLogin]
后台显示异常
- 运行
/api/db/init初始化数据库 - 检查数据库连接是否正常
- 清除浏览器缓存（Cmd+Shift+R）
- 查看浏览器控制台错误
搜索功能无结果
- 检查
public/book-chapters.json是否存在 - 检查章节文件路径是否正确（filePath字段）
- 检查关键词编码（中文需URL编码）
提现失败
- 检查用户余额是否充足
- 检查用户是否有openId
- 检查微信商户API证书配置
- 查看后端日志
[Withdraw]
创建时间：2026-01-25 更新时间：2026-01-25 版本：v3.1（新增实战经验库） 维护者：卡若