做微信小程序代开发的兄弟应该都遇到过这个尴尬模板小程序一套代码写完、审核过了结果每个客户的个性化配置全得手工改代码重新发版。几十个商户就是几十次重复劳动改错一个直接带崩整个包。uni-app 微信第三方平台这套组合天生就是为了解决这种批量交付的痛点而ext.json就是整套方案里最容易被忽略、也最容易翻车的那个文件。这篇文章我按实际踩坑的顺序写适合两类人看。一类是刚接手第三方平台代开发、连ext.json应该放哪个目录都不清楚的 uni-app 新手另一类是已经会填字段但页面起不来、参数取不到、打包后文件莫名消失的老手。我会先讲清楚ext.json在第三方平台链路里到底扮演什么角色再给出 uni-app 项目里的具体配置步骤、每个字段的含义和验证方法最后把高频报错一次性捋完。文章里的例子都是我在真实商户项目里用过的可以直接抄。1. 先搞明白第三方平台和 ext.json 是干嘛的1.1 什么业务才会碰上第三方平台先用大白话讲清楚微信第三方平台的适用场景。普通开发者自己注册一个小程序自己写代码、自己提交审核这个流程完全用不到第三方平台甚至没必要知道ext.json的存在。真正需要第三方平台的是那种“一套模板代码批量给几百个商户生成并维护小程序”的 SaaS 服务商。举几个典型例子你可能立刻就有画面感了做餐饮点餐 SaaS给每个餐厅一个小程序页面结构一模一样但每个小程序的店铺名称、接口域名、菜品数据都不同。做教育机构管理系统给每个培训机构一个小程序报名页面、课表页面、老师介绍页公用一套模板但每家机构的品牌色和联系方式不同。做多商户电商平台给每个入驻品牌一个小程序首页轮播图、优惠券配置、下单接口各不相同。这种模式下服务商不可能给每家商户单独拉一个代码仓库去开发那会把人累死。正确做法是把公共逻辑抽成一个“模板小程序”然后在模板之上通过配置实现差异化。微信官方给这套玩法提供的标准化机制就是第三方平台而模板小程序里用来承载“差异化配置”的文件就是ext.json。1.2 ext.json 在代开发链路里的真实位置理解ext.json的位置很关键很多人配置出错就是因为没搞懂它到底在哪一层生效。整个第三方平台代开发的完整链路是这样的服务商在微信开放平台注册第三方平台账号上传“模板小程序”代码并获取模板 ID。商户通过授权链接把自己的小程序授权给服务商。授权完成后服务商调用上传代码接口把“模板 ID ext_json 内容”一起提交给微信服务器微信服务器把模板代码实例化成商户实际可用的版本。重点来了真正的生产环境里每个商户的差异化配置是服务商后台在调用上传代码接口时动态拼出来的 ext_json 字符串。而ext.json文件在小程序代码包里的作用更多是“开发阶段模拟实例化效果”以及在本地调试时让微信开发者工具知道这套模板该按什么参数运行。所以你在 uni-app 里配置ext.json本质上是给模板小程序准备了一个默认的、可供本地调试的实例化配置文件。它会被原样打包进编译产物微信开发者工具在本地以第三方平台模式打开项目时会读取并匹配它。1.3 它和普通小程序的 app.json/pages.json 有什么区别很多从普通小程序转过来的开发者会问uni-app 里已经有 pages.json 和 manifest.json 了为什么还需要 ext.json这俩根本不是一回事。pages.json是 uni-app 编译时用来生成微信小程序app.json和各个页面 json 的源文件它描述的是“这套模板长什么样”属于静态部分。ext.json描述的是“同一个模板在某个具体商户手里应该表现成什么样”属于动态覆盖层。你可以把模板理解成毛坯房pages.json决定了户型结构ext.json则是每个住户入住时自己贴的墙纸、选的家具。户型是固定的墙纸各不相同。实际操作中ext.json的覆盖逻辑是在微信侧的它能在小程序运行时覆盖模板里已有的页面窗口配置还能给小程序注入自定义字段这些能力pages.json给不了。这也是为什么即使你用 uni-app也不能想当然地跳过ext.json。2. uni-app 项目里 ext.json 的正确放法和最小配置2.1 位置和命名为什么放错一定翻车ext.json放错位置是我见过最多的问题。uni-app 和原生微信小程序的工程结构不一样原生小程序直接放在项目根目录而 uni-app 要看你的工程是 CLI 创建的还是 HBuilderX 创建的。先判断你的工程结构。打开项目根目录如果能看到src文件夹src/pages.json、src/manifest.json、src/main.js都在里面那你就是 CLI 创建的 uni-app 项目ext.json必须放在src目录下和pages.json平级。如果项目根目录就是pages.json、manifest.json、App.vue直接平铺没有src这一层那就是 HBuilderX 创建的标准项目ext.json直接放项目根目录。为什么位置这么敏感因为 uni-app 编译时会把自己认识的源文件交给编译器处理同时把src目录下的其他静态文件原样复制到dist输出目录。你把ext.json放在src下它就能在编译后被复制到dist/dev/mp-weixin下。如果你放错到别的目录比如扔进static文件夹编译后它虽然存在但路径变成了static/ext.json微信开发者工具根本不会去那个位置找。放在项目根目录的 CLI 项目同理因为编译输出只认src目录。命名也必须严格是全小写ext.json微信在解析这个文件时对文件名是大小写敏感的。我见过有人手滑写成Ext.json调试了大半天死活不生效最后查文件名才找到原因。2.2 一份可以直接抄的最小配置先给你一个最小可用的完整配置后面再逐字段拆{ extEnable: true, extAppid: wx1234567890abcdef, extPages: { pages/index/index: { navigationBarTitleText: 某某商户首页 } }, ext: { apiBaseUrl: https://api.example.com, tenantId: demo, themeColor: #ff6600 }, window: { navigationBarBackgroundColor: #ff6600, navigationBarTextStyle: white } }把这串 JSON 保存为ext.json放进src目录编译后你会看到dist/dev/mp-weixin/ext.json这个文件原样生成。extEnable设为true是必须的extAppid先填你所在第三方平台的 appidext里放业务自定义参数window里配置全局窗口覆盖。至于能否生效后面我会给验证方法。这里提醒两个 JSON 本身的坑不要写注释。JSON 不是 JavaScript里面一行//注释都会导致解析失败。不要写尾逗号。最后一个字段后面多一个逗号微信开发者工具直接不认。我自己是写完后习惯放到 jsonlint 之类的工具里过一遍再保存。2.3 编译后如何确认文件进了产物配置文件放好之后第一件事不是急着去微信开发者工具看效果而是先检查编译产物。以 CLI 项目为例执行npm run dev:mp-weixin或npm run build:mp-weixin之后去dist/dev/mp-weixin目录下直接看有没有ext.json。HBuilderX 项目则是去unpackage/dist/dev/mp-weixin下看。如果文件存在打开确认内容和源文件一致这一步能排除大部分低级放错位置的错误。我在实际项目里还遇到过一种情况第一次编译时ext.json在后面改了内容再编译文件却不更新了。这种通常不是 uni-app 的 bug而是微信开发者工具的编译缓存没刷新。解决办法是在微信开发者工具里点“清缓存 - 全部清除”然后重新编译。后面会细说这个坑。3. 核心字段逐个过一遍踩过的坑都写在里面3.1 extAppid 填谁、extEnable 怎么才算开先解释extAppid。这个字段填的是第三方平台自己的 appid也就是服务商在微信开放平台注册第三方平台账号后获得的那一串wx开头的 ID不是商户小程序的 appid也不是模板小程序的 appid。我在刚接触这个配置时犯过糊涂把授权商户的 appid 填了进去结果本地调试时 ext.json 完全不生效控制台还报了一堆授权校验错误。后来翻了微信开放平台的资料才明白extAppid是给微信服务器做关系校验用的它标识的是“这套模板实例化操作属于哪个服务商”。如果你把它填成商户 appid微信拿着这个 ID 去开放平台匹配第三方平台信息自然匹配不上。extEnable同样是必填字段值必须是布尔值true或false注意不是字符串true。JSON 里写成字符串虽然语法合法但微信侧解析后拿到的类型是 string逻辑判断时true和true的性质完全不一样很容易出玄学问题。如果这个字段不填或者填了false整个 ext.json 的作用就会被关闭哪怕其他字段写得再对也没用。3.2 extPages 是页面级覆盖不是新增页面extPages的作用是覆盖模板里已有页面的窗口配置。它的结构是一个对象键是页面路径值是该页面的窗口配置对象支持的配置项和微信小程序页面 json 里的窗口配置一致比如navigationBarTitleText、navigationBarBackgroundColor、enablePullDownRefresh等。这里有个特别容易踩的坑extPages只能覆盖已有页面不能新增页面。如果你在extPages里写了一个模板 pages.json 里根本不存在的路径微信开发者工具不会报错但也不会有任何效果这个配置就像不存在一样。调试的时候特别容易产生“我明明配了为什么不生效”的困惑检查半天才发现路径写错了。路径的写法和 uni-app 里 pages.json 保持一致的风格以pages/开头不写.vue后缀也不写.html后缀只写到目录级文件名。比如 uni-app 里的页面文件是src/pages/order/list.vue那微信小程序里的路径就是pages/order/list在 extPages 里也要用这个路径。再补充一点extPages里配置的页面标题等窗口参数优先级高于模板页面 json 里的配置但低于基础库层面“页面首次渲染的实际参数”严格来说微信文档定义的优先级是页面 json 的配置会覆盖 app.json window 的全局配置而 extPages 的配置会覆盖页面 json 的配置。我实测下来在第三方平台模板包里extPages 对标题和导航栏的覆盖是生效的但是如果页面代码里用了uni.setNavigationBarTitle动态改标题那运行时的动态调用优先级更高毕竟代码里的强制赋值是最后执行的。3.3 ext 自定义字段的读写姿势ext是给开发者自由发挥的区域可以放任意 JSON 对象比如接口域名、商户 ID、主题色、功能开关等业务参数。小程序端获取它的方法是wx.getExtConfigSync()或wx.getExtConfig()前者同步返回后者异步回调。在 uni-app 项目里我会建议把读取逻辑封装成一个公共模块只在微信小程序端生效避免其他端的兼容问题// utils/extConfig.js export function getExtConfig() { // #ifdef MP-WEIXIN try { const config wx.getExtConfigSync() if (config config.tenantId) { return config } } catch (e) { console.error([extConfig] getExtConfigSync fail:, e) } // #endif return {} }然后在App.vue的onLaunch里调用一次存到 Vuex 或者 globalDataimport { getExtConfig } from /utils/extConfig export default { onLaunch() { const extConfig getExtConfig() // 存入 globalData 或 Vuex this.globalData.tenantId extConfig.tenantId || this.globalData.apiBaseUrl extConfig.apiBaseUrl || } }这里有个使用经验要分享ext里的数据是“跟着实例化配置走的”也就是说不同商户的小程序实例打开之后读到的 ext 内容可以不同。这正是它能支撑多商户的核心原因。在本地开发时你读到的是ext.json文件里写的固定内容在正式环境跑起来后读到的是服务商后台动态生成的内容。所以我建议项目里凡是涉及商户身份的配置都走 ext 通道而不是写死在代码里否则这套模板的通用性就大打折扣了。另外wx.getExtConfigSync()在基础库 2.2.3 以下是不支持的如果你的目标用户里有大量低版本微信客户端需要在调用前做能力检测或者兜底走异步版本并做超时处理。虽然现在低版本占比已经很小但做 toB SaaS 的公司往往会收到“某个老手机打不开”的工单提前处理总比事后救火舒服。3.4 window 覆盖的优先级链条ext.json里的window字段和微信小程序app.json里的window字段结构一致用于覆盖全局窗口配置比如导航栏背景色、导航栏文字颜色、背景色等。配置生效的优先级链条是这样的我实际验证过uni-app 默认值 pages.json 里的 globalStyle ext.json 里的 window 页面自己的 window 配置页面 json也就是说如果pages.json的globalStyle里把导航栏背景色设成了白色但某个商户在ext.json的window里设成了橙色最终这个商户的小程序里导航栏就是橙色。如果某个页面自己的 json 里又设了蓝色那么这个页面打开时显示蓝色。理解这条优先级链很重要因为很多多商户配置需求就是靠这个覆盖机制实现的。比如服务商在后台创建小程序时商户上传自己的品牌色服务商把这个颜色写进动态生成的 ext_json 里整个小程序的所有页面导航栏和全局背景就自动换了颜色模板代码一行都不用动。这里要注意window能覆盖的字段有限不是 app.json 里所有字段都支持。我踩过的具体例子是backgroundColor底部背景色可以覆盖但navigationStyle想从默认导航改成自定义导航就不一定灵具体还要以微信文档最新说明为准。所以别抱着“只要 window 里写了就一定能覆盖”的想法涉及比较特殊的配置最好在微信开发者工具里实测一下。4. 用 ext.json 做多商户实例化的实战思路4.1 一个点餐 SaaS 的典型需求拿我自己做过的点餐 SaaS 举例。整个模板有首页、菜单页、购物车页、订单页、我的页五个 tab页面代码完全共用。每个商户的小程序需要差异化的东西包括导航栏标题、主题色、接口域名、商户 ID以及“极简模式”和“标准模式”两个功能开关。如果不用第三方平台的 ext 机制你只能写死一套配置然后靠后端下发动态配置每次启动先去请求接口拿配置再渲染又慢又容易闪白屏。用了ext.json之后这些差异化信息在小程序启动前就已经注入到代码包配置里了模板代码里直接同步读取启动就是最终状态体验好了不止一个台阶。具体到 uni-app 里我大概是这样组织的ext.json里的ext.tenantId标识当前是哪个商户ext.themeColor控制全局主题色ext.apiBaseUrl控制接口请求域名ext.extPages覆盖每个 tab 页面的导航栏标题这样一套模板就能服务几百个商户而且新商户接入时不需要任何人改代码服务商后台生成一份 ext_json 实例化即可。4.2 启动参数代码里怎么优雅地取到商户身份前面提过用wx.getExtConfigSync()读取配置这里再往深一点说怎么把商户身份优雅地传到业务代码里。我的做法是在App.vue的onLaunch里集中读取一次然后放进全局 store。所有页面通过 store 读取避免每个页面都调用wx.getExtConfigSync()。这样做的原因有三个第一getExtConfigSync虽然是同步 API但在极端情况下可能有性能损耗集中在启动时读一次就够了。第二如果后续要扩展逻辑比如做配置白名单校验、默认值兜底只需要改一个地方。第三小程序端的 config 在某个版本开始被注入时机影响早读早安心。实际操作时还要注意一个顺序问题。App.vue的onLaunch执行时间非常早如果页面在onLoad里就要用到商户 ID理论上 store 里已经有值了因为onLaunch在页面onLoad之前触发。但如果你把读取逻辑放在某个页面的onLoad里才第一次执行那么同一个页面内同步拿是没问题的跨页面跳转时也基本没问题。稳妥起见还是建议放App.vue里统一处理。另外uni-app 的onLaunch里等globalData赋值完成再继续有些异步 API 会延迟但getExtConfigSync是同步的即时可用不用担心。4.3 开发和正式环境的差异别在本地测了假配置讲一个很多人都会误解的点你在 uni-app 项目里写死的ext.json主要服务的是开发和本地调试阶段。真正上线时每个商户的 ext_json 内容往往是服务商后台在调用微信上传代码接口时动态传入的不一定和你本地ext.json完全一样。打个比方你本地ext.json里tenantId写的是demo但商户 A 的正式小程序打开后tenantId是服务商后台拼进去的tenant_001商户 B 打开后是tenant_002。这完全正常也是这套机制的精髓。所以做开发时要区分清楚本地开发ext.json文件直接生效适合调试页面表现和逻辑。体验版/正式版以服务商后台调用接口时传的 ext_json 为准代码包里的默认ext.json在实例化时可能被替换或合并。这就意味着你开发时一定要尽量让本地ext.json覆盖到所有可能的业务分支比如没有themeColor时走默认色apiBaseUrl为空时给提示而不是假设 ext 一定存在某字段。否则可能出现“本地好好的上线后商户数据渲染不出来”的尴尬局面。另外要留意ext.json里不要放任何敏感信息比如 appsecret、支付私钥、数据库密码。因为ext字段里的内容在小程序端是能被读出来的所有必须保密的逻辑一律走后端接口前端 ext 只放身份标识和可公开的展示配置。5. 打包、验证与高频报错排查清单5.1 从 uni-app 跑到微信开发者工具的完整路径先说 CLI 项目的流程。在终端执行npm run dev:mp-weixin如果没有这个脚本检查package.json里scripts是否配了。正常跑完编译后打开微信开发者工具选择“导入项目”目录选dist/dev/mp-weixin。这里注意如果你用的是第三方平台模式需要在微信开发者工具的“详情 - 本地设置”里确认项目类型能识别到第三方平台相关的配置否则ext.json可能不生效。HBuilderX 项目更简单菜单栏选“运行 - 运行到小程序模拟器 - 微信开发者工具”它自动把编译产物放到unpackage/dist/dev/mp-weixin并唤起开发者工具。你也可以选“发行 - 小程序-微信”生成生产环境包。第一次跑到微信开发者工具后我习惯先在文件树里找ext.json。能找到就说明它进入代码包了读出来的内容对不对再按下一步验证。5.2 三步自检确认 ext.json 真的生效了文件在不代表配置生效这是过来人的经验。我给自己定的验证流程是三步。第一步看ext.json内容。点开微信开发者工具左侧文件树里的ext.json确认里面的extEnable是trueextAppid没有填错ext字段里的默认值符合预期。第二步直接在小程序代码里读取验证。不需要额外写页面打开微信开发者工具的调试器 Console输入wx.getExtConfigSync()回车如果能看到你ext字段里的配置对象说明 ext 配置链路是通的。如果返回空对象或者报错说明extEnable没打开或者你没有以第三方平台模式运行项目。第三步看extPages和window是否生效。最简单的办法是看导航栏标题和背景色。如果配置里写了一个醒目的标题启动页面却没变化优先检查路径写法是否正确再检查是否有页面级 json 或代码里动态设置标题覆盖了配置。三步走完基本能确认为什么没生效。5.3 高频问题表把我在多个项目里遇到的高频问题整理成一张表方便排查现象可能原因解决办法编译产物里没有 ext.json文件放错目录没放在 src 或项目根目录移到正确目录重新编译ext.json 存在但配置不生效extEnable 没设为 true或不是布尔类型改成extEnable: true读取 getExtConfigSync 返回空对象未以第三方平台模式打开项目或 extEnable 为 false检查项目运行模式确认 extEnable读取 getExtConfigSync 报错基础库版本过低API 不支持升级基础库或改用异步版本extPages 配置的标题不显示页面路径写错或用错文件后缀按pages/目录/文件名路径核对window 配置不生效部分字段覆盖不了页面级 json 的 window 配置优先级更高或字段不被支持检查页面 json确认字段是否在支持范围修改 ext.json 后效果没变化编译缓存或微信开发者工具缓存清空 dist 目录重新编译清缓存后再运行extAppid 填错线上实例化报错填了商户 appid 或模板 appid改成第三方平台自己的 appid这些坑里面最隐蔽的是“ext.json 改了但没重新编译”。uni-app 增量编译时某些情况下新增文件能被识别但如果只是改了内容文件监听有时候会漏掉。我养成的习惯是每次改完 ext.json先手动删除dist或unpackage/dist下对应平台的目录再重新编译。虽然多花几秒钟但能省掉一个大下午的排查时间。另外强调一个工程上的小技巧把ext.json里的公共默认值和服务商后台动态生成的模板分开管理。本地ext.json只是开发用默认值真正的生产实例化参数由服务商后台配置中心统一维护两边共用同一套 JSON Schema。我在后台管理界面让运营填tenantId、themeColor、apiBaseUrl等字段后台再拼成 ext_json 交给微信接口上传。这样前端模板和后端配置各司其职远比让开发在 ext.json 里硬改地址更可控。最后再分享一个我自己的习惯无论项目多急ext.json提交前一定做三件事。第一确认extEnable是布尔值true而不是字符串第二在编译后的 dist 目录里打开ext.json确认它没有丢失且内容是最新的第三在微信开发者工具里执行一次wx.getExtConfigSync()看输出结果和预期是否一致。这三步做完基本不会再出现发布后才发现配置没生效的事故。这套流程我用了很久项目从几个商户扩到几百个商户没在这上面翻过车。
做微信小程序代开发的兄弟应该都遇到过这个尴尬模板小程序一套代码写完、审核过了结果每个客户的个性化配置全得手工改代码重新发版。几十个商户就是几十次重复劳动改错一个直接带崩整个包。uni-app 微信第三方平台这套组合天生就是为了解决这种批量交付的痛点而ext.json就是整套方案里最容易被忽略、也最容易翻车的那个文件。这篇文章我按实际踩坑的顺序写适合两类人看。一类是刚接手第三方平台代开发、连ext.json应该放哪个目录都不清楚的 uni-app 新手另一类是已经会填字段但页面起不来、参数取不到、打包后文件莫名消失的老手。我会先讲清楚ext.json在第三方平台链路里到底扮演什么角色再给出 uni-app 项目里的具体配置步骤、每个字段的含义和验证方法最后把高频报错一次性捋完。文章里的例子都是我在真实商户项目里用过的可以直接抄。1. 先搞明白第三方平台和 ext.json 是干嘛的1.1 什么业务才会碰上第三方平台先用大白话讲清楚微信第三方平台的适用场景。普通开发者自己注册一个小程序自己写代码、自己提交审核这个流程完全用不到第三方平台甚至没必要知道ext.json的存在。真正需要第三方平台的是那种“一套模板代码批量给几百个商户生成并维护小程序”的 SaaS 服务商。举几个典型例子你可能立刻就有画面感了做餐饮点餐 SaaS给每个餐厅一个小程序页面结构一模一样但每个小程序的店铺名称、接口域名、菜品数据都不同。做教育机构管理系统给每个培训机构一个小程序报名页面、课表页面、老师介绍页公用一套模板但每家机构的品牌色和联系方式不同。做多商户电商平台给每个入驻品牌一个小程序首页轮播图、优惠券配置、下单接口各不相同。这种模式下服务商不可能给每家商户单独拉一个代码仓库去开发那会把人累死。正确做法是把公共逻辑抽成一个“模板小程序”然后在模板之上通过配置实现差异化。微信官方给这套玩法提供的标准化机制就是第三方平台而模板小程序里用来承载“差异化配置”的文件就是ext.json。1.2 ext.json 在代开发链路里的真实位置理解ext.json的位置很关键很多人配置出错就是因为没搞懂它到底在哪一层生效。整个第三方平台代开发的完整链路是这样的服务商在微信开放平台注册第三方平台账号上传“模板小程序”代码并获取模板 ID。商户通过授权链接把自己的小程序授权给服务商。授权完成后服务商调用上传代码接口把“模板 ID ext_json 内容”一起提交给微信服务器微信服务器把模板代码实例化成商户实际可用的版本。重点来了真正的生产环境里每个商户的差异化配置是服务商后台在调用上传代码接口时动态拼出来的 ext_json 字符串。而ext.json文件在小程序代码包里的作用更多是“开发阶段模拟实例化效果”以及在本地调试时让微信开发者工具知道这套模板该按什么参数运行。所以你在 uni-app 里配置ext.json本质上是给模板小程序准备了一个默认的、可供本地调试的实例化配置文件。它会被原样打包进编译产物微信开发者工具在本地以第三方平台模式打开项目时会读取并匹配它。1.3 它和普通小程序的 app.json/pages.json 有什么区别很多从普通小程序转过来的开发者会问uni-app 里已经有 pages.json 和 manifest.json 了为什么还需要 ext.json这俩根本不是一回事。pages.json是 uni-app 编译时用来生成微信小程序app.json和各个页面 json 的源文件它描述的是“这套模板长什么样”属于静态部分。ext.json描述的是“同一个模板在某个具体商户手里应该表现成什么样”属于动态覆盖层。你可以把模板理解成毛坯房pages.json决定了户型结构ext.json则是每个住户入住时自己贴的墙纸、选的家具。户型是固定的墙纸各不相同。实际操作中ext.json的覆盖逻辑是在微信侧的它能在小程序运行时覆盖模板里已有的页面窗口配置还能给小程序注入自定义字段这些能力pages.json给不了。这也是为什么即使你用 uni-app也不能想当然地跳过ext.json。2. uni-app 项目里 ext.json 的正确放法和最小配置2.1 位置和命名为什么放错一定翻车ext.json放错位置是我见过最多的问题。uni-app 和原生微信小程序的工程结构不一样原生小程序直接放在项目根目录而 uni-app 要看你的工程是 CLI 创建的还是 HBuilderX 创建的。先判断你的工程结构。打开项目根目录如果能看到src文件夹src/pages.json、src/manifest.json、src/main.js都在里面那你就是 CLI 创建的 uni-app 项目ext.json必须放在src目录下和pages.json平级。如果项目根目录就是pages.json、manifest.json、App.vue直接平铺没有src这一层那就是 HBuilderX 创建的标准项目ext.json直接放项目根目录。为什么位置这么敏感因为 uni-app 编译时会把自己认识的源文件交给编译器处理同时把src目录下的其他静态文件原样复制到dist输出目录。你把ext.json放在src下它就能在编译后被复制到dist/dev/mp-weixin下。如果你放错到别的目录比如扔进static文件夹编译后它虽然存在但路径变成了static/ext.json微信开发者工具根本不会去那个位置找。放在项目根目录的 CLI 项目同理因为编译输出只认src目录。命名也必须严格是全小写ext.json微信在解析这个文件时对文件名是大小写敏感的。我见过有人手滑写成Ext.json调试了大半天死活不生效最后查文件名才找到原因。2.2 一份可以直接抄的最小配置先给你一个最小可用的完整配置后面再逐字段拆{ extEnable: true, extAppid: wx1234567890abcdef, extPages: { pages/index/index: { navigationBarTitleText: 某某商户首页 } }, ext: { apiBaseUrl: https://api.example.com, tenantId: demo, themeColor: #ff6600 }, window: { navigationBarBackgroundColor: #ff6600, navigationBarTextStyle: white } }把这串 JSON 保存为ext.json放进src目录编译后你会看到dist/dev/mp-weixin/ext.json这个文件原样生成。extEnable设为true是必须的extAppid先填你所在第三方平台的 appidext里放业务自定义参数window里配置全局窗口覆盖。至于能否生效后面我会给验证方法。这里提醒两个 JSON 本身的坑不要写注释。JSON 不是 JavaScript里面一行//注释都会导致解析失败。不要写尾逗号。最后一个字段后面多一个逗号微信开发者工具直接不认。我自己是写完后习惯放到 jsonlint 之类的工具里过一遍再保存。2.3 编译后如何确认文件进了产物配置文件放好之后第一件事不是急着去微信开发者工具看效果而是先检查编译产物。以 CLI 项目为例执行npm run dev:mp-weixin或npm run build:mp-weixin之后去dist/dev/mp-weixin目录下直接看有没有ext.json。HBuilderX 项目则是去unpackage/dist/dev/mp-weixin下看。如果文件存在打开确认内容和源文件一致这一步能排除大部分低级放错位置的错误。我在实际项目里还遇到过一种情况第一次编译时ext.json在后面改了内容再编译文件却不更新了。这种通常不是 uni-app 的 bug而是微信开发者工具的编译缓存没刷新。解决办法是在微信开发者工具里点“清缓存 - 全部清除”然后重新编译。后面会细说这个坑。3. 核心字段逐个过一遍踩过的坑都写在里面3.1 extAppid 填谁、extEnable 怎么才算开先解释extAppid。这个字段填的是第三方平台自己的 appid也就是服务商在微信开放平台注册第三方平台账号后获得的那一串wx开头的 ID不是商户小程序的 appid也不是模板小程序的 appid。我在刚接触这个配置时犯过糊涂把授权商户的 appid 填了进去结果本地调试时 ext.json 完全不生效控制台还报了一堆授权校验错误。后来翻了微信开放平台的资料才明白extAppid是给微信服务器做关系校验用的它标识的是“这套模板实例化操作属于哪个服务商”。如果你把它填成商户 appid微信拿着这个 ID 去开放平台匹配第三方平台信息自然匹配不上。extEnable同样是必填字段值必须是布尔值true或false注意不是字符串true。JSON 里写成字符串虽然语法合法但微信侧解析后拿到的类型是 string逻辑判断时true和true的性质完全不一样很容易出玄学问题。如果这个字段不填或者填了false整个 ext.json 的作用就会被关闭哪怕其他字段写得再对也没用。3.2 extPages 是页面级覆盖不是新增页面extPages的作用是覆盖模板里已有页面的窗口配置。它的结构是一个对象键是页面路径值是该页面的窗口配置对象支持的配置项和微信小程序页面 json 里的窗口配置一致比如navigationBarTitleText、navigationBarBackgroundColor、enablePullDownRefresh等。这里有个特别容易踩的坑extPages只能覆盖已有页面不能新增页面。如果你在extPages里写了一个模板 pages.json 里根本不存在的路径微信开发者工具不会报错但也不会有任何效果这个配置就像不存在一样。调试的时候特别容易产生“我明明配了为什么不生效”的困惑检查半天才发现路径写错了。路径的写法和 uni-app 里 pages.json 保持一致的风格以pages/开头不写.vue后缀也不写.html后缀只写到目录级文件名。比如 uni-app 里的页面文件是src/pages/order/list.vue那微信小程序里的路径就是pages/order/list在 extPages 里也要用这个路径。再补充一点extPages里配置的页面标题等窗口参数优先级高于模板页面 json 里的配置但低于基础库层面“页面首次渲染的实际参数”严格来说微信文档定义的优先级是页面 json 的配置会覆盖 app.json window 的全局配置而 extPages 的配置会覆盖页面 json 的配置。我实测下来在第三方平台模板包里extPages 对标题和导航栏的覆盖是生效的但是如果页面代码里用了uni.setNavigationBarTitle动态改标题那运行时的动态调用优先级更高毕竟代码里的强制赋值是最后执行的。3.3 ext 自定义字段的读写姿势ext是给开发者自由发挥的区域可以放任意 JSON 对象比如接口域名、商户 ID、主题色、功能开关等业务参数。小程序端获取它的方法是wx.getExtConfigSync()或wx.getExtConfig()前者同步返回后者异步回调。在 uni-app 项目里我会建议把读取逻辑封装成一个公共模块只在微信小程序端生效避免其他端的兼容问题// utils/extConfig.js export function getExtConfig() { // #ifdef MP-WEIXIN try { const config wx.getExtConfigSync() if (config config.tenantId) { return config } } catch (e) { console.error([extConfig] getExtConfigSync fail:, e) } // #endif return {} }然后在App.vue的onLaunch里调用一次存到 Vuex 或者 globalDataimport { getExtConfig } from /utils/extConfig export default { onLaunch() { const extConfig getExtConfig() // 存入 globalData 或 Vuex this.globalData.tenantId extConfig.tenantId || this.globalData.apiBaseUrl extConfig.apiBaseUrl || } }这里有个使用经验要分享ext里的数据是“跟着实例化配置走的”也就是说不同商户的小程序实例打开之后读到的 ext 内容可以不同。这正是它能支撑多商户的核心原因。在本地开发时你读到的是ext.json文件里写的固定内容在正式环境跑起来后读到的是服务商后台动态生成的内容。所以我建议项目里凡是涉及商户身份的配置都走 ext 通道而不是写死在代码里否则这套模板的通用性就大打折扣了。另外wx.getExtConfigSync()在基础库 2.2.3 以下是不支持的如果你的目标用户里有大量低版本微信客户端需要在调用前做能力检测或者兜底走异步版本并做超时处理。虽然现在低版本占比已经很小但做 toB SaaS 的公司往往会收到“某个老手机打不开”的工单提前处理总比事后救火舒服。3.4 window 覆盖的优先级链条ext.json里的window字段和微信小程序app.json里的window字段结构一致用于覆盖全局窗口配置比如导航栏背景色、导航栏文字颜色、背景色等。配置生效的优先级链条是这样的我实际验证过uni-app 默认值 pages.json 里的 globalStyle ext.json 里的 window 页面自己的 window 配置页面 json也就是说如果pages.json的globalStyle里把导航栏背景色设成了白色但某个商户在ext.json的window里设成了橙色最终这个商户的小程序里导航栏就是橙色。如果某个页面自己的 json 里又设了蓝色那么这个页面打开时显示蓝色。理解这条优先级链很重要因为很多多商户配置需求就是靠这个覆盖机制实现的。比如服务商在后台创建小程序时商户上传自己的品牌色服务商把这个颜色写进动态生成的 ext_json 里整个小程序的所有页面导航栏和全局背景就自动换了颜色模板代码一行都不用动。这里要注意window能覆盖的字段有限不是 app.json 里所有字段都支持。我踩过的具体例子是backgroundColor底部背景色可以覆盖但navigationStyle想从默认导航改成自定义导航就不一定灵具体还要以微信文档最新说明为准。所以别抱着“只要 window 里写了就一定能覆盖”的想法涉及比较特殊的配置最好在微信开发者工具里实测一下。4. 用 ext.json 做多商户实例化的实战思路4.1 一个点餐 SaaS 的典型需求拿我自己做过的点餐 SaaS 举例。整个模板有首页、菜单页、购物车页、订单页、我的页五个 tab页面代码完全共用。每个商户的小程序需要差异化的东西包括导航栏标题、主题色、接口域名、商户 ID以及“极简模式”和“标准模式”两个功能开关。如果不用第三方平台的 ext 机制你只能写死一套配置然后靠后端下发动态配置每次启动先去请求接口拿配置再渲染又慢又容易闪白屏。用了ext.json之后这些差异化信息在小程序启动前就已经注入到代码包配置里了模板代码里直接同步读取启动就是最终状态体验好了不止一个台阶。具体到 uni-app 里我大概是这样组织的ext.json里的ext.tenantId标识当前是哪个商户ext.themeColor控制全局主题色ext.apiBaseUrl控制接口请求域名ext.extPages覆盖每个 tab 页面的导航栏标题这样一套模板就能服务几百个商户而且新商户接入时不需要任何人改代码服务商后台生成一份 ext_json 实例化即可。4.2 启动参数代码里怎么优雅地取到商户身份前面提过用wx.getExtConfigSync()读取配置这里再往深一点说怎么把商户身份优雅地传到业务代码里。我的做法是在App.vue的onLaunch里集中读取一次然后放进全局 store。所有页面通过 store 读取避免每个页面都调用wx.getExtConfigSync()。这样做的原因有三个第一getExtConfigSync虽然是同步 API但在极端情况下可能有性能损耗集中在启动时读一次就够了。第二如果后续要扩展逻辑比如做配置白名单校验、默认值兜底只需要改一个地方。第三小程序端的 config 在某个版本开始被注入时机影响早读早安心。实际操作时还要注意一个顺序问题。App.vue的onLaunch执行时间非常早如果页面在onLoad里就要用到商户 ID理论上 store 里已经有值了因为onLaunch在页面onLoad之前触发。但如果你把读取逻辑放在某个页面的onLoad里才第一次执行那么同一个页面内同步拿是没问题的跨页面跳转时也基本没问题。稳妥起见还是建议放App.vue里统一处理。另外uni-app 的onLaunch里等globalData赋值完成再继续有些异步 API 会延迟但getExtConfigSync是同步的即时可用不用担心。4.3 开发和正式环境的差异别在本地测了假配置讲一个很多人都会误解的点你在 uni-app 项目里写死的ext.json主要服务的是开发和本地调试阶段。真正上线时每个商户的 ext_json 内容往往是服务商后台在调用微信上传代码接口时动态传入的不一定和你本地ext.json完全一样。打个比方你本地ext.json里tenantId写的是demo但商户 A 的正式小程序打开后tenantId是服务商后台拼进去的tenant_001商户 B 打开后是tenant_002。这完全正常也是这套机制的精髓。所以做开发时要区分清楚本地开发ext.json文件直接生效适合调试页面表现和逻辑。体验版/正式版以服务商后台调用接口时传的 ext_json 为准代码包里的默认ext.json在实例化时可能被替换或合并。这就意味着你开发时一定要尽量让本地ext.json覆盖到所有可能的业务分支比如没有themeColor时走默认色apiBaseUrl为空时给提示而不是假设 ext 一定存在某字段。否则可能出现“本地好好的上线后商户数据渲染不出来”的尴尬局面。另外要留意ext.json里不要放任何敏感信息比如 appsecret、支付私钥、数据库密码。因为ext字段里的内容在小程序端是能被读出来的所有必须保密的逻辑一律走后端接口前端 ext 只放身份标识和可公开的展示配置。5. 打包、验证与高频报错排查清单5.1 从 uni-app 跑到微信开发者工具的完整路径先说 CLI 项目的流程。在终端执行npm run dev:mp-weixin如果没有这个脚本检查package.json里scripts是否配了。正常跑完编译后打开微信开发者工具选择“导入项目”目录选dist/dev/mp-weixin。这里注意如果你用的是第三方平台模式需要在微信开发者工具的“详情 - 本地设置”里确认项目类型能识别到第三方平台相关的配置否则ext.json可能不生效。HBuilderX 项目更简单菜单栏选“运行 - 运行到小程序模拟器 - 微信开发者工具”它自动把编译产物放到unpackage/dist/dev/mp-weixin并唤起开发者工具。你也可以选“发行 - 小程序-微信”生成生产环境包。第一次跑到微信开发者工具后我习惯先在文件树里找ext.json。能找到就说明它进入代码包了读出来的内容对不对再按下一步验证。5.2 三步自检确认 ext.json 真的生效了文件在不代表配置生效这是过来人的经验。我给自己定的验证流程是三步。第一步看ext.json内容。点开微信开发者工具左侧文件树里的ext.json确认里面的extEnable是trueextAppid没有填错ext字段里的默认值符合预期。第二步直接在小程序代码里读取验证。不需要额外写页面打开微信开发者工具的调试器 Console输入wx.getExtConfigSync()回车如果能看到你ext字段里的配置对象说明 ext 配置链路是通的。如果返回空对象或者报错说明extEnable没打开或者你没有以第三方平台模式运行项目。第三步看extPages和window是否生效。最简单的办法是看导航栏标题和背景色。如果配置里写了一个醒目的标题启动页面却没变化优先检查路径写法是否正确再检查是否有页面级 json 或代码里动态设置标题覆盖了配置。三步走完基本能确认为什么没生效。5.3 高频问题表把我在多个项目里遇到的高频问题整理成一张表方便排查现象可能原因解决办法编译产物里没有 ext.json文件放错目录没放在 src 或项目根目录移到正确目录重新编译ext.json 存在但配置不生效extEnable 没设为 true或不是布尔类型改成extEnable: true读取 getExtConfigSync 返回空对象未以第三方平台模式打开项目或 extEnable 为 false检查项目运行模式确认 extEnable读取 getExtConfigSync 报错基础库版本过低API 不支持升级基础库或改用异步版本extPages 配置的标题不显示页面路径写错或用错文件后缀按pages/目录/文件名路径核对window 配置不生效部分字段覆盖不了页面级 json 的 window 配置优先级更高或字段不被支持检查页面 json确认字段是否在支持范围修改 ext.json 后效果没变化编译缓存或微信开发者工具缓存清空 dist 目录重新编译清缓存后再运行extAppid 填错线上实例化报错填了商户 appid 或模板 appid改成第三方平台自己的 appid这些坑里面最隐蔽的是“ext.json 改了但没重新编译”。uni-app 增量编译时某些情况下新增文件能被识别但如果只是改了内容文件监听有时候会漏掉。我养成的习惯是每次改完 ext.json先手动删除dist或unpackage/dist下对应平台的目录再重新编译。虽然多花几秒钟但能省掉一个大下午的排查时间。另外强调一个工程上的小技巧把ext.json里的公共默认值和服务商后台动态生成的模板分开管理。本地ext.json只是开发用默认值真正的生产实例化参数由服务商后台配置中心统一维护两边共用同一套 JSON Schema。我在后台管理界面让运营填tenantId、themeColor、apiBaseUrl等字段后台再拼成 ext_json 交给微信接口上传。这样前端模板和后端配置各司其职远比让开发在 ext.json 里硬改地址更可控。最后再分享一个我自己的习惯无论项目多急ext.json提交前一定做三件事。第一确认extEnable是布尔值true而不是字符串第二在编译后的 dist 目录里打开ext.json确认它没有丢失且内容是最新的第三在微信开发者工具里执行一次wx.getExtConfigSync()看输出结果和预期是否一致。这三步做完基本不会再出现发布后才发现配置没生效的事故。这套流程我用了很久项目从几个商户扩到几百个商户没在这上面翻过车。
