AI 微信小程序模板

一个开箱即用的 AI 微信小程序开发模板，提供 Taro 4 + React 小程序、NestJS API、Prisma/MySQL、可配置 AI、ASR/TTS、微信授权与 CloudBase 云托管部署。

• AI：通过 AI_PROVIDER 切换 OpenAI-compatible 或 CloudBase；模型、Base URL、Key、系统提示词和超时均为配置项。
• 语音：腾讯云一句话识别；Edge TTS 带重试；小程序端负责录音、上传、播放与临时文件清理。
• 授权：微信登录、游客体验、手机号授权、麦克风拒绝后的设置引导；服务端 JWT 鉴权。
• 部署：生产 Dockerfile、Prisma migration、健康检查和 npm run deploy。
• 示例：文本/语音提问、AI 对话和回复朗读。

“任意模型”指任何实现 OpenAI Chat Completions 兼容协议的模型服务；非兼容服务只需在 apps/server/src/providers/ai 增加适配器。模型密钥永远不要放进小程序。

要求 Node.js 20+、Docker 和微信开发者工具。

npm install
cp apps/server/.env.example apps/server/.env
docker compose up -d mysql
npm run db:generate
npm run db:migrate
npm run config:check
npm run dev:server

执行 config:check 前，请至少在 apps/server/.env 中替换 JWT_SECRET、AI_MODEL 和所选 AI Provider 的凭证；否则检查会有意失败，避免带着占位配置启动。

另开终端：

npm run dev:miniprogram

用微信开发者工具导入 apps/miniprogram。将 project.config.json 的 appid 替换成自己的 AppID。开发者工具测试本地 API 时可以关闭合法域名校验；真机和正式版必须使用已备案 HTTPS 域名并加入 request、uploadFile 合法域名。

npm run config:check 会检查必填配置，并提示尚未配置的可选语音能力。touristappid 只能用于基础界面调试；微信登录、手机号授权和正式发布必须换成真实 AppID。

AI_PROVIDER=openai-compatible
AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=your-key
AI_MODEL=your-model-id

DeepSeek、通义、豆包或自建网关若提供相同协议，只需替换这三个值。

AI_PROVIDER=cloudbase
AI_MODEL=hy3
CLOUDBASE_ENV_ID=your-env-id
CLOUDBASE_AI_PROVIDER=cloudbase

本地运行还需 CloudBase 调用凭证；云托管可使用平台注入的身份。业务工具调用应在服务端注册，并在真正写入前再次做权限与参数校验。

ASR 使用 ASR_PROVIDER=tencent。配置腾讯云 CAM 最小权限账号的 TENCENT_SECRET_ID、TENCENT_SECRET_KEY、地域、引擎与可选热词。设为 disabled 可完全关闭。

TTS 默认 TTS_PROVIDER=edge，可配置音色、语速和音调。若有大量固定文案，建议增加持久化缓存和预热任务；动态短回复直接生成更简单。

• 首次进入不弹权限框，由用户点击登录或游客体验。
• 微信身份、手机号和麦克风分开按需申请，避免捆绑授权。
• 用户拒绝麦克风后，通过 openSetting 提供明确恢复路径。
• 游客数据通过稳定的本机 guestId 识别。正式业务若要“登录后合并游客数据”，应在领域数据表中增加 ownerId，并在登录事务中迁移，模板不对未知业务数据擅自合并。
• 昵称使用微信当前支持的昵称输入组件采集；不要依赖旧版 getUserProfile 自动获取。若业务需要头像，应接入对象存储后再启用 chooseAvatar，不要把临时文件路径直接保存到数据库。
• 手机号接口只应由用户主动点击 open-type=getPhoneNumber 触发。生产环境应缓存微信 access_token，当前最小实现为清晰起见按请求获取。

上线前必须补充真实《用户协议》《隐私政策》页面，并在微信公众平台声明所用隐私接口。

先安装并登录官方 CLI：

npm install -g @cloudbase/cli
tcb login

设置部署参数并进行预检：

export TCB_ENV_ID=your-env-id
export TCB_SERVICE_NAME=miniapp-ai-api
npm run deploy:check

预检通过后：

npm run deploy

脚本使用 CloudBase 当前的 tcb cloudrun deploy --source . --port 3000 --force。首次部署前，需在控制台创建 MySQL、配置 VPC，并为云托管服务设置 apps/server/.env.example 中的生产环境变量。敏感值不要写入 cloudbaserc.json。

容器启动时先执行 prisma migrate deploy，失败则不启动应用。存活检查为 GET /api/health/live。

构建正式小程序时注入 API 地址：

MINIAPP_API_BASE_URL=https://your-api.example.com/api npm run build:miniprogram

• AI Provider：apps/server/src/providers/ai
• ASR/TTS Provider：apps/server/src/providers/voice
• 授权状态与恢复：apps/miniprogram/src/services/permissions.ts
• 登录态：apps/miniprogram/src/services/session.ts
• 最小 AI 页面：apps/miniprogram/src/pages/index
• 部署入口：scripts/deploy-cloudbase.mjs

1. 替换 AppID、API 域名、协议和隐私政策。
2. 使用高强度且稳定的 JWT_SECRET；配置服务端密钥，确认仓库中没有真实凭证。
3. CloudBase MySQL 仅允许同 VPC 访问，执行 migration 并验证健康检查。
4. 真机验证微信登录、游客模式、手机号拒绝/允许、麦克风拒绝后恢复、ASR、AI、TTS。
5. 为 AI/ASR/TTS 增加限流、费用告警和隐私数据保留策略。