小程序上线前，我踩过的部署坑

上周帮朋友把一个小程序从开发环境推到线上，本来以为半小时能搞定，结果折腾了整整一个下午。踩的坑不算新鲜，但每一个都挺典型，索性记下来，给正在做小程序部署的朋友提个醒。

先说结论：部署不是点一下“上传”就完事

很多人对小程序部署的理解停留在：开发者工具点上传 → 后台提交审核 → 发布。流程没错，但真实项目里，卡住你的往往是上传之前和审核之间的那些细节。

坑一：域名没配好，真机一片空白

开发时勾了“不校验合法域名”，本地一切正常。一上真机，接口全挂。这是最常见的问题，尤其是接手别人项目的时候。

• 登录小程序后台，在「开发管理 → 开发设置 → 服务器域名」里配置 request、uploadFile、downloadFile 等合法域名
• 域名必须已备案，且是 https
• 每月只能修改 5 次，改之前想清楚

如果项目用了云开发，接口走的是云函数，就绕开了域名配置，这也是云开发对独立开发者最友好的地方之一。

坑二：环境变量写死在代码里

这个问题很隐蔽。开发环境的接口地址、appid、各种 key 直接硬编码在 js 里，上传时忘了改，线上就打到测试库了。

// 别这么干
const BASE_URL = 'https://test-api.example.com'

// 推荐：用配置文件区分环境
// config/index.js
const env = 'prod' // 上传前改这里，或者用构建脚本注入
const configs = {
  dev: { baseUrl: 'https://test-api.example.com' },
  prod: { baseUrl: 'https://api.example.com' }
}
export default configs[env]

更稳妥的做法是在 CI 里根据分支自动替换，手动改迟早会忘。

坑三：分包没做，主包超 2M

小程序主包限制 2M，超了直接上传失败。我第一次遇到时一脸懵，后来发现是图片和第三方库塞太多了。

• 图片尽量放 CDN，别打进包里
• 非首屏页面做成分包，用 subpackages 配置
• 第三方 UI 库按需引入，别整包 import

分包配置本身不复杂，麻烦的是拆分时要理清页面之间的依赖，拆完记得在开发者工具里跑一遍“代码依赖分析”。

坑四：审核被拒的理由五花八门

代码没问题，审核也能卡你。我遇到过的：

“请补充完整的功能截图及测试账号”

还有一次是因为页面里有“支付”字样但没接支付，被判为诱导。经验是：

1. 提审时把测试账号、操作路径写清楚，别嫌麻烦
2. 文案里别出现敏感词，尤其是涉及钱、返利、抽奖
3. 首次提审别开太多功能，先上一个能跑通的核心版本

坑五：发布后才发现线上日志看不到

小程序没有服务端那种现成的日志系统。上线后用户报错，你只能靠 wx.getRealtimeLogManager 或者自己上报。建议在部署前就把错误上报接好，哪怕只是往云开发的数据库里写一条记录，也比两眼一抹黑强。

const logger = wx.getRealtimeLogManager()
App({
  onError(err) {
    logger.error('app error', err)
  }
})

一点个人习惯

现在我的部署清单大概是这样的：改环境配置 → 跑依赖分析看包体积 → 真机预览走一遍核心流程 → 上传填版本号和备注 → 后台配域名（如果改了）→ 提审。步骤不多，但每次按顺序过一遍，能省掉大部分返工。

小程序部署这件事，技术难度其实不高，难的是细节多、容错低。把流程固化成清单，比记住每一个坑更靠谱。