微信小程序云开发指南

项目结构

weapp-project/
├── miniprogram/ # 小程序前端代码
│ ├── app.js
│ ├── app.json
│ ├── app.wxss
│ ├── pages/
│ │ ├── index/ # 页面目录
│ │ │ ├── index.js
│ │ │ ├── index.wxml
│ │ │ ├── index.wxss
│ │ │ └── index.json
│ │ └── ...
│ ├── components/
│ ├── utils/
│ └── images/
├── cloudfunctions/ # 云函数目录
│ ├── getTaskProgress/
│ │ ├── index.js
│ │ └── package.json
│ └── ...
├── cloudbaserc # 云开发配置
├── project.config.json # 小程序项目配置
└── key/
└── private.key # 微信公众号密钥

关键配置文件

project.config.json

json { appid: your-appid, cloudfunctionRoot: cloudfunctions/, setting: { urlCheck: false, es6: true, enhance: true } }

云函数 package.json

json { name: function-name, version: 1.0.0, dependencies: { wx-server-sdk: ~2.6.3 } }

miniprogram-ci 常用命令

部署云函数

bash npx miniprogram-ci cloud functions upload \ --pp ./ \ --pkp ./key/private.key \ -r 1 \ -e cloudbase-环境ID \ -n 函数名 \ -p ./cloudfunctions/函数名 \ --rnpm

参数说明：

• - --pp: 项目路径
• --pkp: 私钥路径
• -r: 机器人编号 (1-30)
• -e: 云开发环境ID
• -n: 云函数名称
• -p: 云函数代码路径
• --rnpm: 远程安装依赖

预览小程序

bash npx miniprogram-ci preview \ --pp ./miniprogram \ --pkp ./key/private.key \ --qr-dest ./preview-qrcode.png \ --qr-format image \ --appid your-appid \ -r 1 \ --enable-qrcode true \ --uv 1.0.0 \ --threads 0 \ --use-cos false

上传小程序

bash npx miniprogram-ci upload \ --pp ./miniprogram \ --pkp ./key/private.key \ --appid your-appid \ -r 1 \ --uv 1.0.0 \ --ud 更新描述

云函数开发要点

初始化云开发

javascript const cloud = require(wx-server-sdk) cloud.init({ env: cloud.DYNAMICCURRENTENV })

const db = cloud.database()

获取用户信息

javascript const { OPENID } = cloud.getWXContext()

获取临时文件URL

javascript async function getTempFileURL(fileID) { if (!fileID) return null try { const result = await cloud.getTempFileURL({ fileList: [fileID] }) if (result.fileList && result.fileList[0]) { return result.fileList[0].tempFileURL } } catch (e) { console.error(获取临时URL失败:, e) } return null }

调用其他云函数

javascript const result = await cloud.callFunction({ name: 函数名, data: { / 参数 / } })

图像处理扩展

安装扩展

在云开发控制台 → 扩展能力 → 安装「图像处理」

使用示例

javascript const extCi = require(@cloudbase/extension-ci) cloud.registerExtension(extCi)

// 添加水印
const res = await cloud.invokeExtension(CloudInfinite, {
action: WaterMark,
cloudPath: target.jpg,
fileContent: imageBuffer,
operations: {
rules: [{
fileid: output.jpg,
rule: {
mode: 3,
type: 2,
text: 水印文字,
gravity: SouthEast
}
}]
}
})

常见问题

⚠️ 重要：wx.requestSubscribeMessage 调用规范

微信规定：订阅消息授权必须在用户点击事件的回调函数中同步触发，否则会失败。

正确做法：
javascript
// ❌ 错误：在异步回调中调用（云函数返回后才调用）
async submit() {
await wx.cloud.callFunction({ name: xxx })
wx.requestSubscribeMessage({ tmplIds: [...] }) // 太晚了！
}

// ✅ 正确：在点击事件第一时间同步调用
async submit() {
wx.requestSubscribeMessage({ tmplIds: [...] }) // 立即调用
await wx.cloud.callFunction({ name: xxx }) // 然后再做其他事
}

关键点：

1. 1. 必须在 bindtap 或 catchtap 回调的同步流程中调用
2. 不能放在 setTimeout、异步 await、或任何回调链的后面
3. 推荐在 onLoad 时预获取模板ID，存入 data，点击时直接从 data 读取

---

Q: 云函数上传失败 ResourceNotFound.Function

A: 需要先在微信开发者工具中手动创建云函数一次，然后再用 ci 上传更新

Q: 预览二维码失效

A: 尝试更换版本号 --uv 1.0.X，多次尝试

Q: getTempFileURL 返回 undefined

A: 检查 fileID 是否为云存储的 fileID，外部URL不需要转换

Q: cloud.init 报错

A: 确保在云函数中初始化，客户端使用 wx.cloud

Q: 云函数依赖安装失败

A: 使用 --rnpm 参数让云端安装依赖，或检查 package.json