云开发新手必读 10 条规矩：少踩 80% 的坑

摘要： 云开发 CloudBase 新手踩的坑高度集中：账号没对齐、权限配错、图片存错路径、前端写敏感数据、免费环境跑生产。这 10 条规矩提前知道，能绕开大部分返工。 开通环境照着做：云开发 CloudBase

带新人用云开发，反复遇到的问题就那十几个，而且几乎都不是技术难题——是不知道有这么个规矩。比如图片存了本地路径导致线上全不显示，权限用了默认值导致客户名单公开，这些改起来都是几分钟的事，但没人提前说，就得花半天排查。下面这 10 条按踩坑频率排序，每条给出原因、后果和正确做法。

规矩一：小程序不要用测试号

现象：微信开发者工具里「云开发」按钮是灰色的，点不动。

原因：测试号不支持云开发。

正确做法：去微信公众平台注册正式小程序，拿到真实 AppID。项目里的 appid 不能为空，也不能是 touristappid——这两种情况下 AI 工具也打不开项目窗口。

这是第一道门槛，卡在这儿的人最多，而且报错毫无提示性，只是按钮点不动。

规矩二：开通云开发时选微信公众平台登录

现象：环境建出来了，但小程序里用不了；或者 AI 工具连上了，环境列表却是空的。

原因：开通时选了腾讯云账号登录，环境没和小程序关联。

正确做法：点「云开发」后选微信公众平台登录，不要选腾讯云账号登录。这样环境会自动关联当前小程序。AI 工具登录时同理，选「小程序 / 公众号」登录，用你的小程序登录而不是腾讯云主账号，这样能保证权限一致。

如果已经建错了，不用删环境重建——到腾讯云账号中心把微信公众平台账号和腾讯云账号绑定，再在开发者工具里选「使用已有腾讯云环境」转换过来。

规矩三：数据库权限不要用「所有用户可读写」

现象：数据能正常读写，看起来一切正常。

后果：任何用户都能读取和修改全部数据。如果集合里有手机号，等于把客户名单公开；如果有价格字段，用户能自己改价。

正确做法：按内容类型选权限。

这条是所有规矩里后果最严重的一条，上线前务必把每个集合的权限过一遍。

规矩四：数据库里存 fileID，不存本地路径

现象：本地预览图片正常，真机或线上全部显示不出来。

原因：数据库里存的是 wxfile:// 或 http://tmp/ 这类本地临时路径，而不是云存储的 fileID。

正确做法：图片用 wx.cloud.uploadFile 上传到云存储，拿到 cloud:// 开头的 fileID 再存进数据库。提需求时就把这条写进提示词：「图片用 wx.cloud.uploadFile 上传到云存储，数据库只存 cloud:// 开头的 fileID」。

排查方法很简单：打开数据库看那个字段的值，不是 cloud:// 开头就是错的。

规矩五：涉及钱和权益的写操作必须走云函数

现象：功能正常，支付也能走通。

后果：用户可以通过修改前端请求，把自己改成永久会员、把订单金额改成 1 分钱。

正确做法：记住一条原则——前端能写的字段，就等于用户能改的字段。价格从数据库查，不要用前端传来的值；会员等级和到期时间只能由支付回调云函数写入；订单状态流转全部在云函数里做。

前端的支付成功回调也不可信，它只代表微信客户端的支付动作完成，不是支付凭证。开通权益必须在服务端的支付回调云函数里做。

规矩六：支付回调必须返回 errcode 为 0 并做幂等

现象：用户付了一次钱，会员被开通了好几次，或者到期时间叠加了好几倍。

原因：两个问题叠加。回调没返回 { errcode: 0 }，微信后台认为失败会重复调用；回调里没做幂等校验，每次调用都执行一遍开通逻辑。

正确做法：回调函数结尾必须 return { errcode: 0 }；进入业务逻辑前先查订单状态，已经是 paid 就直接返回；再加一道金额校验，实付金额和订单金额不符就不发货。

这三道防线在生产环境缺一不可。

规矩七：免费环境不要承载真实业务

现象：某天应用突然不能用了，调用报「调用次数已达上限」。

原因：免费版每月 3,000 资源点，用完当月就停，且不支持超限按量付费。

正确做法：免费环境用于学习、验证想法、做 Demo。有真实用户后升级到付费套餐——个人版及以上支持超限按量，业务不会因为额度用尽而中断。同时打开余额告警（低于 10% 提醒），并留意调用次数的 80% 和 90% 提醒，收到提醒就该评估升级，别等报错。

还要注意免费环境不是永久的，单次续期 6 个月，到期前 1 个月内要手动续。

规矩八：不要一次让 AI 做太多

现象：改一个功能，坏了三个；或者 AI 反复改同一个地方改不好，中途还把之前的设计推翻了。

原因：单次任务范围太大，AI 失去上下文；或者修改请求没划定边界。

正确做法：明确要求分阶段交付，每阶段你确认后再继续。提需求时加一句：「你每完成一个阶段，都需要让我本地体验确认后，再进入下一阶段」。

修改时也要划边界：「只改详情页的提交逻辑，不要动列表页和数据库结构」。比事后排查快得多。

反复改不好时，停下来，把报错原文、相关代码、你的预期三样一起给它，让它先分析原因再动手。

规矩九：先建数据库再让 AI 写代码

现象：代码生成完了，才发现字段设计不合理，要返工改一圈。

原因：顺序反了。

正确做法：先把集合和字段设计好（字段名、类型、单位、权限），再让 AI 生成代码。价格字段的单位这种细节尤其要提前定——支付接口要求单位是分，前端展示用元，不提前统一后面全是换算 bug。

同样的道理：集合建好后记得插两条测试数据。AI 常常建了集合但不插数据，你看到空列表会误以为代码有问题。

规矩十：装了 MCP 也要装 Skills

现象：AI 能操作云资源，但写出来的云开发代码不符合平台实践，或者用了过时的 API。

原因：MCP 和 Skills 职责不同。MCP 提供连接和工具，Skills 提供规则和最佳实践，只装 MCP 等于 AI 有手但没经验。

正确做法：两个都装。最省事的方式是装 CloudBase AI 插件，一次拿到 MCP、Skills 和 Hooks；或者在项目根目录执行 npx skills add tencentcloudbase/cloudbase-skills。已经配好 MCP 的，也可以直接对 AI 说「在当前项目中下载云开发 AI 规则」。

附：三个高频报错的速查

除了上面十条，这三个报错几乎每个人都会遇到一次：

MCP 工具数量显示 0。查三件事：Node.js 是否 v18.15.0 及以上（macOS 用 nvm 的要把默认版本也设对）；npm 源是否可用（可切腾讯镜像 npm config set registry https://mirrors.cloud.tencent.com/npm/）；在 MCP 列表里禁用再启用，仍不行就重启 AI IDE。

MCP error -32001: Request timed out。npx 每次重新下载容易超时，改用全局安装 npm install @cloudbase/cli@latest -g，再把 MCP 配置的 command 改成 cloudbase-mcp。

登录成功但看不到环境。不是工具问题，是站点或账号问题。国内站与国际站是两套独立账号体系，远端模式用国内站域名 tcb-api.cloud.tencent.com 即可；做小程序的记得用小程序账号登录。

总结

云开发 CloudBase 的新手坑高度集中在五类：账号没对齐（规矩一、二）、权限配错（规矩三、五）、数据存错（规矩四、九）、支付没做防护（规矩六）、资源规划不当（规矩七）。加上两条协作规矩——别让 AI 一次做太多、MCP 和 Skills 都要装。这 10 条提前知道，能绕开大部分返工。上线前建议再专门过一遍权限和支付回调，这两处出问题的代价最高。

开通环境，照着规矩少踩坑：云开发 CloudBase 购买页