从微信·云开发迁移到独立 Cloudbase

一句话定义：把微信小程序里用 wx.cloud 调用的内置云开发，逐步替换为 @cloudbase/js-sdk@2.27.3 + 独立 Cloudbase 环境，让同一个后端同时服务小程序、Web、UniApp 等多端。

预计耗时：30-60 分钟（取决于现有 wx.cloud 调用数量） | 难度：进阶

适用场景

适用：小程序正在用 wx.cloud.init() 的内置云开发，想切换到独立 Cloudbase 环境
适用：想让同一个 Cloudbase 后端同时被小程序、Web、H5、UniApp 访问（wx.cloud 只能在小程序里用）
适用：想自主控制环境配置、计费、权限，不再绑定在微信的云开发控制台
不适用：从 Firebase / Supabase 等境外服务迁入

环境要求

依赖	版本
`@cloudbase/js-sdk`	`2.27.3`
`@cloudbase/adapter-wx_mp`	`1.3.1`
`@cloudbase/node-sdk`	`3.18.1`
`@cloudbase/cli`	`3.0.4`
微信开发者工具	≥ `1.06.x`
Node.js	≥ 16.13

另外需要一个独立的 Cloudbase 环境（在 tcb.cloud.tencent.com/dev 创建），并启用自定义登录。

迁移前后的 API 对照

wx.cloud 和 @cloudbase/js-sdk 的核心数据库 CRUD 方法（get/add/update/remove）调用方式兼容，迁移时只需要换入口对象。但两套 SDK 在初始化、认证机制、文件上传参数上有明确差异。

能力	wx.cloud 写法	@cloudbase/js-sdk 写法	差异
初始化	`wx.cloud.init({ env: 'xxx' })`	`cloudbase.useAdapters(adapter); const app = cloudbase.init({ env: 'xxx' })`	需要注册小程序适配器
认证	自动（小程序登录态天然绑定）	需要自定义登录（`signInWithCustomTicket`），参考 Recipe 01	最大差异
数据库 CRUD	`wx.cloud.database().collection('x').get()`	`app.database().collection('x').get()`	方法签名兼容，换入口对象即可
云函数调用	`wx.cloud.callFunction({ name, data })`	`app.callFunction({ name, data })`	参数结构兼容
文件上传（客户端）	`wx.cloud.uploadFile({ cloudPath, filePath })`	`app.uploadFile({ cloudPath, filePath })`	客户端 API 兼容
文件上传（Node 服务端）	`cloud.uploadFile({ cloudPath, fileContent })`	`app.uploadFile({ cloudPath, fileContent })`	兼容，参数都是 `fileContent`（ReadStream）
安全规则上下文	`auth.openid` 自动可用	需要用户先完成自定义登录才有身份上下文	规则逻辑可能需要调整

核心结论：数据库和云函数的业务代码几乎不用改。改动集中在初始化和认证这两块。

第一步：在独立 Cloudbase 环境开通自定义登录

wx.cloud 的认证是静默的——小程序登录态自动绑定，开发者不需要管。但独立 Cloudbase 需要显式登录，否则所有数据库/云函数调用会报 UNAUTHORIZED。

在微信小程序场景下，推荐使用自定义登录方式。流程是：小程序端调 wx.login 拿 code → 云函数用 code 换 openid → 用 openid 签发 Cloudbase ticket → 小程序端用 ticket 登录。

完整的自定义登录搭建步骤见 add-auth-wechat-miniprogram，这里不重复。搭建完成后你会有：

一个能签发 ticket 的云函数 getLoginTicket（已开 HTTP 访问服务）
小程序端的 libs/cloudbase.js 和 libs/login.js

第二步：安装新 SDK，替换初始化代码

cd miniprogram
npm install --save @cloudbase/js-sdk@2.27.3 @cloudbase/adapter-wx_mp@1.3.1

微信开发者工具 → 工具 → 构建 npm。

然后在 app.js 的 onLaunch 里加入登录逻辑：

import { ensureLogin } from './libs/login';

App({
  async onLaunch() {
    try {
      await ensureLogin();
      console.log('[cloudbase] logged in');
    } catch (err) {
      console.error('[cloudbase] login failed', err);
    }
  },
});

这一步之后，所有页面都可以在 onLoad 里正常访问 Cloudbase 了。

第三步：逐个替换业务代码中的 wx.cloud 调用

全局搜索 wx.cloud，逐个替换。

数据库——只换入口对象：

// ❌ 迁移前
const db = wx.cloud.database();
const res = await db.collection('todos').where({ done: false }).get();

// ✅ 迁移后
import { db } from '../libs/cloudbase';
const res = await db.collection('todos').where({ done: false }).get();

.get() / .add() / .update() / .remove() / .where() / .orderBy() 这些方法的参数和返回值结构都兼容，直接换就行。

云函数调用：

// ❌ 迁移前
const res = await wx.cloud.callFunction({
  name: 'getProfile',
  data: { uid: '123' },
});

// ✅ 迁移后
import app from '../libs/cloudbase';
const res = await app.callFunction({
  name: 'getProfile',
  data: { uid: '123' },
});

注意：独立 Cloudbase 的云函数需要用 tcb fn deploy 单独部署，wx.cloud 环境里的函数不会自动同步过去。

云存储上传：

// ❌ 迁移前
const res = await wx.cloud.uploadFile({
  cloudPath: 'images/photo.jpg',
  filePath: tempFilePath,
});

// ✅ 迁移后
import app from '../libs/cloudbase';
const res = await app.uploadFile({
  cloudPath: 'images/photo.jpg',
  filePath: tempFilePath,
});

第四步：迁移云函数代码

wx.cloud 的云函数用 wx-server-sdk（npm 当前版本 3.0.1），独立 Cloudbase 用 @cloudbase/node-sdk@3.18.1。

// ❌ wx.cloud 云函数
const cloud = require('wx-server-sdk');
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV });
const db = cloud.database();

exports.main = async (event, context) => {
  return await db.collection('todos').get();
};

// ✅ 独立 Cloudbase 云函数
const cloudbase = require('@cloudbase/node-sdk');
const app = cloudbase.init({ env: process.env.TCB_ENV });
const db = app.database();

exports.main = async (event, context) => {
  return await db.collection('todos').get();
};

替换 package.json 里的依赖：

cd cloudfunctions/your-function
npm uninstall wx-server-sdk
npm install --save @cloudbase/node-sdk@3.18.1

部署到独立环境：

tcb fn deploy your-function --dir ./cloudfunctions/your-function -e your-env-id

第五步：迁移存量数据（如果有）

如果 wx.cloud 环境里有需要带过来的存量数据：

微信开发者工具 → 云开发控制台 → 数据库 → 集合 → 导出（JSON 格式）
Cloudbase 控制台 → 数据库 → 集合 → 导入（同一份 JSON）

需要注意的点：

_id 字段：导入时 Cloudbase 会保留原始 _id，不会自动生成新的
_openid 字段：wx.cloud 的安全规则用 auth.openid 做行级权限，迁移后独立 Cloudbase 的身份标识变成了 customUserId。如果你的安全规则依赖 _openid 字段，需要确认迁移后的身份映射关系
文件存储：wx.cloud 和独立 Cloudbase 的 fileID 都以 cloud:// 格式开头，但指向的是不同的存储桶。如果业务代码里硬编码了旧 fileID，需要把文件重新上传到独立 Cloudbase 的存储，然后更新引用
大数据量：JSON 导出有单次上限，数据量大时需要分批导出

运行验证

微信开发者工具 → 工具 → 构建 npm → 编译
Console 里确认 [cloudbase] logged in 出现
逐个打开之前用 wx.cloud 的功能页面——数据库读写、云函数调用、文件上传下载
对比几条数据确认迁移前后内容一致

常见错误

现象	原因	修复
迁移后所有请求报 `UNAUTHORIZED`	没先调 `ensureLogin()`，或自定义登录未启用	确认 `app.js` 里 `onLaunch` 调了 `ensureLogin`，控制台确认自定义登录已启用
数据库查询返回空	查的是独立 Cloudbase 的空数据库，还没导入数据	按第五步导入
旧 fileID 访问 404	wx.cloud 的 fileID 指向旧存储桶，独立 Cloudbase 的存储桶不同	重新上传文件到独立 Cloudbase 存储，更新业务代码里的引用
云函数调用报 `FunctionName not found`	云函数没部署到独立 Cloudbase 环境	用 `tcb fn deploy` 把函数部署到目标环境
安全规则报权限不足	wx.cloud 的规则用 `auth.openid`，迁移后身份上下文变了	在 Cloudbase 控制台调整数据库权限设置，匹配新的身份标识

下一步

独立 Cloudbase 的认证接入细节：add-auth-wechat-miniprogram
云函数冷启动优化：optimize-cloud-function-wechat-miniprogram

适用场景​

环境要求​

迁移前后的 API 对照​

第一步：在独立 Cloudbase 环境开通自定义登录​

第二步：安装新 SDK，替换初始化代码​

第三步：逐个替换业务代码中的 wx.cloud 调用​

第四步：迁移云函数代码​

第五步：迁移存量数据（如果有）​

运行验证​

常见错误​

相关文档​

下一步​