uni-app 最吸引人的地方，是一套代码可以发布到多个平台。

这句话没错。

但很多新手会误会成，发布也只需要点一个按钮。

真不是。

H5、小程序、App 的上线方式、审核规则、缓存策略、回滚方式、版本管理都不一样。你在开发阶段享受“统一”，在发布阶段必须尊重“差异”。

这一篇不追求讲完所有平台规则。

我们只把一个商品应用从开发到上线最容易踩的发布问题讲清楚。

太长不看版

发布前先问四个问题。

1. 我要发到哪个平台，H5、微信小程序、App，还是多个一起发？
2. 当前构建连接的是开发接口、测试接口，还是生产接口？
3. 平台需要的域名、权限、隐私协议、版本号、证书都配好了吗？
4. 发出去之后，发现问题怎么观察、怎么降级、怎么回滚？

开发时你可以想“一套代码”。

发布时一定要按平台拆开想。

这一篇放在系列里的位置

如果你还没做上线前检查，先看 10-上线前检查清单.md。

如果你担心权限和隐私，回看 14-安全防护与数据保护.md。

如果你还没做真机和异常测试，先看 15-测试调试与质量保证.md。

这一篇解决的是，代码写完以后怎么发出去，怎么别把开发环境、错误配置和不可回滚风险一起发出去。

先看三条发布路径

同一份 uni-app 源码，最后会走到不同平台。

看起来都是“发行”。

但每条路要检查的东西不同。

发布前先做环境隔离

上线事故里，有一种特别低级，但特别常见。

生产包连到了测试接口。

或者测试包连到了生产支付。

这种问题不靠“我记得改了”来解决。要靠环境配置集中管理。

// 文件位置：config/env.js

constconfigs={development:{baseURL:'https://dev-api.example.com',enableDebug:true},test:{baseURL:'https://test-api.example.com',enableDebug:true},production:{baseURL:'https://api.example.com',enableDebug:false}}exportconstappConfig=configs[process.env.NODE_ENV]||configs.development

请求封装里只读配置。

// 文件位置：utils/request.js

import{appConfig}from'@/config/env'exportconstrequest=(options)=>{returnnewPromise((resolve,reject)=>{uni.request({url:`${appConfig.baseURL}${options.url}`,method:options.method||'GET',data:options.data||{},success:resolve,fail:reject})})}

关键点是，页面不要到处写死接口域名。

域名散落在页面里，最后一定会有人漏改。

H5 发布，看资源路径、路由刷新和缓存

H5 发布最像普通前端项目。

你构建出一批静态文件，然后放到服务器、对象存储或 CDN 上。

H5 最常见的问题有三个。

资源路径错了

商品图片、JS、CSS 加载 404，页面白屏或样式丢失。

如果你的站点部署在子路径，比如https://example.com/goods-app/，就要确认构建配置里的基础路径是否匹配。

发布后打开浏览器 DevTools，先看 Network 有没有红色 404。

刷新深层页面 404

用户直接打开商品详情页，或者在详情页刷新。

如果服务端没有做好回退配置，可能直接 404。

如果你用的是前端路由模式，要让服务器把未知前端路径回退到index.html。不同服务器配置方式不同，但思路一样。

CDN 缓存导致旧代码还在

你发了新版本，但用户看到的还是旧页面。

这通常是缓存问题。

发布 H5 时，建议静态资源文件带 hash，HTML 不要缓存太久。这样 JS/CSS 可以长缓存，入口 HTML 可以尽快拿到新版本。

微信小程序发布，看 appid、合法域名、包体积和审核

小程序不是把 H5 丢上服务器。

它有平台规则。

商品应用上线微信小程序前，至少检查这些。

小程序发布一般会经历这样的流程。

有一点要特别注意。

小程序审核是需要时间的。

所以如果你上线后才发现重大问题，修复节奏不会像 H5 那么自由。上线前的测试和灰度体验就更重要。

App 发布，看证书、版本号、权限和应用市场规则

App 发布比 H5 和小程序更重。

你要考虑 Android 和 iOS 的包名、证书、版本号、权限、隐私政策、应用市场审核。

最容易被忽略的是版本号。

一般会有两个概念。

不要只改展示版本，不改构建版本。

否则应用市场或系统可能判断不出这是一个新包。

权限也要克制。

如果商品应用只做浏览和发布，可能需要相册、相机、网络。除非你真的做“附近商品”，否则不要随便申请定位。权限越多，审核风险越高，用户也越不信任。

分包和预加载，不是上线前才想起来

前面 13-性能优化入门.md 讲过分包和预加载。发布阶段要再核一次。

pages.json里可以配置页面、tabBar、subPackages、preloadRule 等。官方文档里也明确，preloadRule可以在进入小程序某个页面时预下载可能需要的分包，用来提升后续页面启动速度。

一个商品应用可以这样理解。

不要把所有页面都塞进主包。

但也不要为了分包而分包。首页、tabBar、首屏关键页面一般留在主包，低频大功能再考虑拆出去。

条件编译要集中，不要撒满页面

发布多端时，平台差异不可避免。

uni-app 支持条件编译，比如#ifdef H5、#ifdef MP-WEIXIN、#ifdef APP-PLUS。官方文档里也提到，条件编译可以用于 JS、模板、CSS、pages.json、static 等场景。

但条件编译不是越多越好。

错误倾向是每个页面都写一堆平台判断。

更好的做法是把平台差异封装成方法。

// 文件位置：utils/platform.js

exportconstgetShareChannel=()=>{// #ifdef MP-WEIXINreturn'wechat-mini-program'// #endif// #ifdef H5return'h5'// #endif// #ifdef APP-PLUSreturn'app'// #endifreturn'unknown'}

页面里只调用getShareChannel()。

这样以后平台逻辑改了，不需要到处找。

发布后要观察，不要发完就关电脑

发布不是最后一步。

发布后至少观察这些。

• 页面白屏率。
• 接口错误率。
• 登录失败率。
• 商品发布成功率。
• 图片上传失败率。
• 小程序审核反馈。
• 应用市场崩溃反馈。

如果你暂时没有专业监控，也可以先做最朴素的发布记录。

// 文件位置：docs/release-log.md

# 发布记录 ## v1.0.0 - 发布时间： - 发布平台： - 构建环境： - 主要改动： - 影响页面： - 回滚方式： - 发布后观察：

发布记录的价值，不在于形式。

而是出问题时你能知道，这次到底改了什么。

回滚和降级，要提前想

小项目也要有退路。

H5 可以回滚到上一版静态资源。

小程序可以视情况回退线上版本或重新提交审核。

App 如果已经发到市场，回滚成本更高，所以更需要灰度、版本控制和服务端降级开关。

如果某个新功能风险高，比如商品发布页改了上传流程，可以让后端加一个开关，异常时先关闭新入口。不要把所有风险都押在重新发包上。

这里容易翻车

1. 生产包连着测试接口，或者测试包连着生产支付。
2. H5 部署到子路径后静态资源 404。
3. 深层页面刷新 404，以为是前端路由坏了，其实是服务器没回退。
4. CDN 缓存没处理，用户一直加载旧 JS。
5. 小程序忘记配置 request/uploadFile 合法域名。
6. 权限申请和实际功能不匹配，审核或用户信任出问题。
7. App 只改versionName，没改构建版本号。
8. 发布后没有观察指标，用户反馈了才知道线上坏了。

自己试试

1. 给项目加一个config/env.js，把开发、测试、生产接口地址集中管理。
2. 写一份docs/release-log.md发布记录模板。
3. 检查manifest.json和pages.json，列出当前项目发布到 H5、小程序、App 分别要改哪些配置。
4. 模拟一次 H5 发布后回滚，写出你会恢复哪一版文件、清哪些缓存、通知谁验证。

这一篇先记住什么

uni-app 帮你统一了开发体验。

但它没有消灭平台发布差异。

H5 看资源路径、路由刷新、缓存和回滚。

小程序看 appid、合法域名、包体积、隐私协议和审核。

App 看证书、版本号、权限、市场规则和升级策略。

所有平台都要先做好环境隔离，再做发布记录，再做发布后观察。

上线不是把代码扔出去。

上线是把风险有控制地交给真实用户。