唐山小程序开发：从上线到部署的实战避坑

上个月帮唐山一位做烘焙连锁的客户处理了一次上线事故。代码本地跑得好好的，提交审核被驳回两次，第三次过了，结果发布后用户打开一片白屏。折腾到凌晨两点，问题出在环境变量没配全，还有一处域名没加进白名单。这类事在小程序开发里太常见了，尤其对第一次做小程序的本地商家来说，部署这一步往往比写代码更磨人。我是知码客，专注小程序和 APP 开发，今天就把部署这块的实战经验摊开说说。

为什么部署比开发更容易翻车

小程序和传统 Web 不一样，它跑在微信的容器里，你没法直接登录服务器看日志。开发阶段用的是开发者工具的模拟环境，很多问题会被掩盖：

• 本地接口写的是 localhost，真机访问不到
• 测试用的 AppID 和正式的不一致，支付、订阅消息全部失效
• 图片资源放在本地目录，包体超了 2MB 主包限制
• 云开发环境 ID 忘了切，数据写进了测试库

唐山不少做餐饮、建材、教培的老板找我聊的时候，都以为「代码写完就等于上线了」。实际上从提审到发布，中间还有配置、审核、灰度、监控几道关。下面按顺序讲。

第一步：把环境配置彻底分开

建议项目里建三套配置，开发、体验、正式。用构建脚本注入，不要靠手动改代码。

// config/index.js
const envMap = {
  develop: { api: 'https://dev.api.example.com', cloudEnv: 'dev-xxxx' },
  trial:   { api: 'https://test.api.example.com', cloudEnv: 'test-xxxx' },
  release: { api: 'https://api.example.com',     cloudEnv: 'prod-xxxx' }
};
module.exports = envMap[process.env.NODE_ENV || 'develop'];

微信开发者工具里可以设置编译模式，配合 project.config.json 的 condition 字段，一键切换。这一步做好，后面能省掉一大半低级错误。

第二步：域名与服务器配置

小程序要求所有请求走 HTTPS，且域名必须在后台「开发管理 - 服务器域名」里登记。注意几个细节：

• 主域名和子域名要分别配置，通配符不生效
• 备案主体最好和账号主体一致，唐山本地企业备案一般 3 到 7 个工作日
• websocket、上传、下载是分开填的，别漏
• 如果用了第三方 CDN，也要把 CDN 域名加进去

我见过一个唐山做家居的客户，图片走的是对象存储，结果只配了接口域名，商品图全部 403，上线当天客服电话被打爆。

第三步：包体瘦身与分包

主包上限 2MB，整个项目 20MB。很多小程序一上来就把所有页面塞主包，提审直接失败。做法是：

1. 首页、tabBar 页面放主包，其余按业务拆分包
2. 图片压缩后上传 CDN，不要打进代码包
3. 第三方 SDK 按需引入，能放分包就放分包
4. 用 --analyze 看依赖体积，找出大块头

分包配置在 app.json 里写 subpackages，注意分包之间不能互相引用，公共代码要抽到主包或者独立分包。

第四步：提审与发布的节奏

审核这块有几个经验：

• 类目要和实际业务匹配，唐山做本地生活服务的，别选成电商平台
• 涉及用户信息的页面，隐私协议要能点开且内容真实
• 审核期间别频繁改代码，改一次重新排队
• 首次发布建议先「体验版」给客户内部走一遍完整流程

发布后不要一次性全量。微信支持分阶段发布，先放 10%，观察一天错误率和接口耗时，没问题再逐步放开。这个功能很多人不知道，其实能救命。

第五步：上线后的监控

上线不是终点。至少要做三件事：

• 接入实时日志，关注 JS 错误和接口失败率
• 给关键接口加耗时上报，唐山本地用户网络环境差异大，弱网表现要单独看
• 版本回滚预案提前写好，出问题能在十分钟内退回上一版

部署这件事，拼的不是技术多深，而是细节有没有闭环。一个域名、一个环境变量，就能让几个月的开发成果卡在最后一步。

写在最后

知码客在唐山做小程序和 APP 开发这些年，接过不少「半路接手」的项目，问题大多集中在部署配置和上线流程上。如果你正在唐山做小程序，或者手里的项目卡在提审、白屏、支付调不通这些环节，欢迎聊聊。代码写得好是本事，能稳稳当当地跑在用户手机上，才算真正交付。