上一篇文章我们把多客户配置的目录结构和基础思路定下来了今天把话接上聊一聊真正核心的部分怎么让 Vue 项目在多个客户、多套环境之间切换的时候不再靠“人肉改代码”。这篇我会把拆解思路、运行时配置模型、自动生成入口、构建流水线接入全讲清楚也会附上我自己踩过的坑。内容基于 Vue 3 Vite但 Vue 2 webpack 的思路完全一致迁移成本不高。多客户配置这件事表面上看着就是“把 API 域名换成客户的”实际上往里走一步就会发现问题远不止 API 域名每个客户的 Logo、主题色、备案号、功能开关、菜单权限、甚至某些页面组件都不一样。如果这些全部靠环境变量硬编码很快你就会被客户数量乘以环境数量给吞掉。我看过不少团队配置维护靠一个共享 Excel上线靠微信群喊“谁改过 customerA 的配置”最后发布错了客户回滚还要折腾半天。自动化方案要解决的根本不是“能不能自动”而是把变化的边界划清楚让变化只在该变化的地方发生。1. 先把“多客户配置”这件事拆透1.1 客户配置到底都隔些什么先盘一单动手写方案之前我习惯先给配置项分个类因为不同类别的配置生命周期和注入时机完全不一样。我把实际项目里的客户配置归纳成四类你拿这个清单去套自己的项目基本是够用的类别典型字段变化频率注入时机品牌与展示类站点标题、Logo、主题色、备案号、版权文案低基本定下来就不动运行期注入接口与基础服务类API Base URL、WebSocket 地址、文件服务地址、埋点 ID中环境切换必改运行期注入功能开关与权限类是否开启报表、是否启用 IM、菜单可见性、角色权限高业务运营经常调运行期注入构建与环境类publicPath、CDN 域名、是否开启 sourcemap极低改了就要重新构建构建期注入看到没有前两类是“随站点走”的后两类里构建与环境是“随代码走”的。很多团队把四类全塞进.env文件然后每个客户复制一份.env.customerA每次构建传--mode customerA。这个做法临时能用但有一个致命问题只要改了 API 域名或者开关就必须重新执行一次构建。客户 A 有 3 个环境客户 B 有 3 个环境改一个 Logo 要等六次流水线跑完资源浪费还是小事情关键是发布窗口拉长出错概率成倍增加。所以我在设计这套方案时第一原则就是凡是运行期能变的绝不放到构建期去定死。1.2 构建期变量与运行期配置的边界这是新旧方案的唯一分水岭理解这个边界是整套方案的钥匙。构建期变量比如VITE_PUBLIC_PATH、VITE_CDN它们在vite build执行的时候就会被静态替换进产物打包结束后这些值已经焊死在 JS 里面了改也只能重新构建。运行期配置则相反它是页面加载后从某个外部文件读取的只要换掉外部文件不用动产物刷新页面就是新配置。打个比方构建期变量是房子的地基和承重墙浇筑完了就定型运行期配置是软装和智能家居设置换个用户入住直接调设置就行。你不可能为了换一套沙发改地基。确定了这个边界后方案的核心骨架就很清晰了构建期只保留那些真正和打包路径相关的变量其余客户差异项全部抽到一个运行时站点配置对象里。这个对象里存的是一份普通 JSON不参与打包、不参与编译由浏览器在页面加载时同步读取。这样一来“产物”和“站点数据”就彻底解耦了你可以做到一份 Vue 构建产物对应任意数量的客户站点。这一步想通了后面所有实现都是水到渠成的事不用纠结“为什么不能直接在代码里 import 一个 config.ts”。因为一旦 import配置就进了 bundle你又回到了“改配置必须重新构建”的老路。2. 一套可落地的配置矩阵把“客户”和“环境”组合成二维坐标系2.1 配置矩阵长什么样配置不是一堆散文件它需要有一个干净的坐标体系。我常用的矩阵是两个维度客户维度tenant× 环境维度env。客户是横轴环境是纵轴交叉点就是一个具体的配置文件。客户 \ 环境devtestprodcustomerAsite.customerA.dev.jsonsite.customerA.test.jsonsite.customerA.prod.jsoncustomerBsite.customerB.dev.jsonsite.customerB.test.jsonsite.customerB.prod.jsoncustomerCsite.customerC.dev.jsonsite.customerC.test.jsonsite.customerC.prod.json这个矩阵的好处是任何一个配置问题你都能第一时间定位到“哪个客户、哪个环境”的交叉点。我在实际项目里还会在 JSON 里加一个_meta字段专门记录这个配置文件最后是谁改的、什么时候改的、对应前端产物版本是什么排查线上问题的时候非常救命不然两个客户共用一个产物出了问题互相甩锅都不知道是谁动了配置。文件命名规范我用的是小写加点的形式site.{customer}.{env}.json。这个命名规则不是随便定的因为后续自动化脚本要用正则从文件名里解析维度和值命名越规律脚本越简单越不容易出错。你要是喜欢用customerA_prod.json也行但全项目必须只有一个规范文件名就是接口协议。2.2 为什么不能只搞一个 “config-production.js”我见过有的团队说“我们也有多客户配置”结果就是一个config/prod.js里面写export default { customerA: { apiBase: https://a.example.com }, customerB: { apiBase: https://b.example.com } }然后代码里到处config[customerName]。这个方案不是不能用但它把两个问题混淆了第一它把所有客户的配置打进了同一个 bundle客户 A 永远会下载到客户 B 的敏感信息第二它没有环境维度测试环境联调的时候你根本没法模拟线上差异。正确的做法是每个客户每个环境一个独立文件构建物是“通用壳子”加载哪个配置由站点入口决定。客户 A 和生产环境的关系应该在“站点”这一层就确定下来而不是在代码里动态认领。站点配置的下发本质上是部署行为不是代码行为。想清楚这句话整套方案的架构就会很干净。3. 核心实操运行时站点配置 自动生成入口3.1 目录结构设计说再多理论不如直接看目录。我推荐把运行时配置放在 Vue 项目的public/config/目录下注意是public不是src。原因是public下的文件会被原样拷贝到构建产物的根目录不会被 Vite 处理、不会被打包、不会有 hash 后缀非常干净。public/config/ ├── site.json # 默认配置作为兜底 ├── site.customerA.dev.json ├── site.customerA.test.json ├── site.customerA.prod.json ├── site.customerB.dev.json ├── site.customerB.test.json └── site.customerB.prod.json程序入口这边index.html里会通过一段同步脚本去加载对应配置。为什么不用fetch异步拉因为配置要在 Vue 应用实例化之前就位如果用异步请求首屏会出现一段没有站点标题、没有主题色的白屏而且fetch跨域、超时的问题都要额外处理。同步script加载是浏览器原生能力最简单也最可靠。3.2 配置加载的时序和注入方式先看index.html里的加载逻辑。这里我用了动态判断域名的方式让一个构建产物能同时服务多个客户!DOCTYPE html html langzh-CN head script src/config/runtime-loader.js/script script // 加载完 loader 后同步阻塞直到站点配置写入 window var __site window.__siteLoader window.__siteLoader(); window.__SITE_CONFIG__ __site || window.__DEFAULT_SITE__ || {}; document.title window.__SITE_CONFIG__.title || 默认标题; /script /head body div idapp/div script typemodule src/src/main.ts/script /body /html关键就在runtime-loader.js。它的职责是根据当前域名判断是哪个客户然后同步加载对应的配置文件。这是文件的核心逻辑// public/config/runtime-loader.js (function (win) { var hostMap { localhost: site.customerA.dev.json, a.example.com: site.customerA.prod.json, b.example.com: site.customerB.prod.json }; var fileName hostMap[win.location.hostname] || site.json; // 同步阻塞加载指定配置文件避免首屏闪烁 document.write(script src/config/ fileName \/script); // 暴露统一入口把配置对象交出去 win.__siteLoader function () { return win.__SITE_CONFIG_RAW__ || null; }; })(window);对应地每个site.customerA.prod.json我并不是直接放纯 JSON 文件而是放一段赋值全局变量的 JS。这样避免了 JSON 文件的 MIME 类型问题也保证同步加载后立刻有值// public/config/site.customerA.prod.json.js window.__SITE_CONFIG_RAW__ { _meta: { customer: customerA, env: prod, version: 1.2.3, updatedAt: 2025-06-18T10:00:0008:00 }, title: A 客户管理后台, logoUrl: /assets/logo-a.png, apiBase: https://api.a.example.com, wsBase: wss://ws.a.example.com, theme: { primaryColor: #1b6ef3, borderRadius: 6 }, features: { report: true, im: false, exportExcel: true } };看到这里你可能会有疑问site.customerA.prod.json.js这个名字挺别扭为什么不干脆叫.js我也不知道最开始谁定的规矩但用.json.js这个后缀最大的好处是 CI 脚本生成文件时可以直接生成标准 JSON再在前后各包一行赋值语句即可Excel、后端同学给的配置模板也不用额外学新格式。这也是一个很实用的经验生成文件时遵循“数据是 JSON、壳子是 JS”的约定人和机器的理解成本都最低。3.3 如何优雅地决定“当前是哪个客户”域名映射表维护起来很简单但并非所有项目都有独立的客户域名。内部联调阶段大家往往是用 IP 加端口访问的这时候再维护 hostMap 就不太现实了。我建议把“决定客户身份”的逻辑做成一个可插拔的解析器优先级从上到下URL 上的显式参数例如?__sitecustomerA本地调试最方便域名映射表线上域名自动匹配部署目录名例如 Nginx 下/customerA/目录前缀兜底默认配置site.json保证裸访问不至于 404。function resolveSiteName() { var q win.location.search.match(/[?]__site([^])/); if (q) return q[1]; var pathMatch win.location.pathname.match(/^\/([^/])\//); if (pathMatch) return pathMatch[1]; var domainMatch hostMap[win.location.hostname]; return domainMatch || ; }这套解析逻辑放在 loader 里前端主代码完全不用关心自己是谁。等 Vue 实例开始干活它只需要读window.__SITE_CONFIG__就行。我在main.js里初始化 Pinia 的时候会把配置对象一次性注入一个useSiteStore里而不是在每个组件里都裸读全局变量。全局变量只作为“注入源”业务代码永远通过 store 读配置这样后续如果要改造成接口下发配置只动 store 的初始化部分就够了。关于 Vue 的组合式和选项式顺带多说一句千万不要在组件的setup里直接访问window.__SITE_CONFIG__这会让你在每个组件里都产生一层未受控的依赖还容易因为Object.freeze丢了响应式而一脸懵。正确做法是像依赖注入一样在入口把配置变成provide提供出来或者放进 Pinia 的 state组件通过storeToRefs按需解构。我见过有人把整个配置对象放进 reactive 里然后发现所有字段都变了深响应式性能崩了半秒钟排查半天才发现是在配置对象里放了图片资源 URL被 Vue 的响应式代理反复复制了一遍。4. 构建与发布侧的自动化把手工降为零4.1 预处理器帮你生成 site 文件配置文件的生成是我这套方案里自动化程度最高的环节。以前我们手动创建 JSON一旦客户多了漏一个字段、写错一个环境线上就是事故。所以我自己写了一个 Node 脚本scripts/site-config.mjs它从一份“配置源”读取数据批量生成所有客户和所有环境的站点文件。配置源我强烈推荐用.env加一份单独维护的config/tenants.json。.env负责放通用构建变量例如VITE_PUBLIC_PATH、VITE_CDN_BASEtenants.json负责放每个客户的差异化字段。举个例子// config/tenants.json { customers: [ { name: customerA, title: A 客户管理后台, apiBase: https://api.a.example.com, features: { report: true } }, { name: customerB, title: B 客户运营平台, apiBase: https://api.b.example.com, features: { report: false, im: true } } ], envs: [dev, test, prod] }脚本做的事情很机械但很治愈遍历customers再遍历envs按环境拼上各自的 API 域名前缀生成 JSON 内容前面包一行window.__SITE_CONFIG_RAW__ 后面补;写到public/config/下。这样新增一个客户只需要在tenants.json里加一行记录然后跑npm run generate:site全部站点配置自动更新。// scripts/site-config.mjs import { writeFileSync, mkdirSync } from node:fs; import { resolve } from node:path; const tenants JSON.parse(readFileSync(config/tenants.json, utf-8)); const outputDir resolve(public/config); mkdirSync(outputDir, { recursive: true }); for (const customer of tenants.customers) { for (const env of tenants.envs) { const config { _meta: { customer: customer.name, env, version: process.env.npm_package_version || unknown, updatedAt: new Date().toISOString() }, title: customer.title, apiBase: customer.apiBase.replace({ENV}, env), features: customer.features }; const content window.__SITE_CONFIG_RAW__ ${JSON.stringify(config, null, 2)};\n; writeFileSync( resolve(outputDir, site.${customer.name}.${env}.json.js), content, utf-8 ); } }这里注意apiBase里我留了{ENV}占位符。因为同一个客户的apiBase在不同环境通常只有子域名前缀不同比如api.a.dev.example.com、api.a.prod.example.com占位符替换比每个组合手写完整 URL 更直观也更容易维护。这也是一个减少手工细节的好习惯。4.2 接入流水线一次构建多处部署配置文件就位后构建自动化就分成两条路我实际项目里两条都用过看团队规模选择。第一种是“一份公共产物运行时选站点”。流水线只跑一次npm run build产物上传到静态服务器或 CDN然后客户域名对应的 Nginx 直接指到同一份产物区别只在于配置目录是否同步替换。这种方式适合客户数量多、每个客户站点入口独立、产品形态几乎一致的情况。我经常在会场上强调这套方案最大的好处是客户 A 如果只想改个标题不用等前端发布直接改配置站点的 JSON 文件刷新立刻生效。对于运营类后台这个诉求特别多省下来的沟通成本是肉眼可见的。第二种是“按客户构建参数交给 CI”。流水线每次部署时通过 CI 变量指定CUSTOMERcustomerA、ENVprod构建命令类似npm run generate:site -- --customer customerA --env prod npm run build这种方式适合客户之间有较多独立逻辑、产物本来就要分开的场景。它仍然比“人肉改 .env”强在所有差异项在tenants.json里统一管理CI 只是把参数从配置源透传给脚本没有人会再去手动改环境变量或代码。我个人的建议是如果你的客户数量不超过三个用第二种一旦超过五个强烈建议往第一种靠。因为客户多了以后维护“每个客户单独构建”本身就是一种负担构建时间、存储空间、发布流程全是成本和风险点。而公共产物加运行时配置才是真正匹配“很多客户、同一套系统、差异由数据驱动”这个业务模型的。5. 常见问题与排查技巧实录5.1 踩过的坑和翻车现场我把平时支持同事时遇到的高频问题整理成一个速查表每个问题背后都是一个真实的翻车现场现象原因解决办法改了site.customerA.prod.json.js线上不生效浏览器缓存或 CDN 缓存了旧的配置文件配置文件名加版本参数如site.customerA.prod.json.js?v20250618或协调 CDN 缓存规则设置较短的 max-age首屏偶发白屏控制台报配置 undefined异步加载配置Vue 初始化早于配置就位确认加载方式是同步script不要用fetch页面 title 一直显示默认值document.title 在 SPA 路由切换后被覆盖在路由全局前置守卫里重新读取 store 里的 title 并赋值客户 A 新增的字段客户 B 的页面报错配置对象校验缺失布局侧强依赖了某字段在 store 初始化时做一次 schema 校验给缺失字段打默认值配置里写了带/的 logo URL却打不开publicPath 是相对路径而站点配置在public/config/子目录下所有资源路径建议以绝对路径/开头或运行时动态拼接 CDN 前缀构建后public/config没出现在 dist 里Vite 配置了publicDir或者构建脚本清理了 dist检查 vite.config 的publicDir不要自己乱清 dist5.2 配置对象到底要不要 freeze要而且要彻底很多人不知道 Object.freeze 这个细节的价值。运行时配置一旦被某个组件不小心this.siteConfig.apiBase https://xxx改掉线上就出现一个“只有那个客户倒霉”的诡异 bug排查成本极高。我在main.js里把配置写进 store 时会做一层Object.freeze(window.__SITE_CONFIG__)。之后任何代码试图修改它非严格模式下静默失败严格模式下直接抛 TypeError问题当场暴露而不是等到线上某个功能不工作了才回头找。这里有个反直觉的坑如果你用ref()包住这个被 freeze 的对象Vue 内部的响应式代理在改写时会出错但你改的对象其实还是原来的普通对象报错信息可能指向 Vue 内部容易让人误判。所以我一般直接用一个普通reactive状态加上readonly方法包一层import { readonly, ref } from vue; const siteConfig readonly(window.__SITE_CONFIG__); const siteStore { config: siteConfig, apiBase: siteConfig.apiBase };配置只读store 只负责向上读取业务往下永远不应该改配置。这个设计原则写进团队规范比在代码里写一百行注释有用。5.3 动态路由和菜单权限的客户差异化处理最后说说菜单权限和动态路由这是多客户配置里最容易失控的部分。有的客户只显示三个菜单有的客户要显示十个有的客户有“数据导出”这个功能有的完全没有。我见过最粗暴的做法是v-iffeatures.xxx写满每个菜单项客户多了以后页面模板像补丁一样脏。我的做法是把菜单和路由的映射做成“配置驱动”。tenants.json里每个客户维护一份menuRoutes数组路由名称和组件路径都用字符串表示页面加载后由前端根据这份配置动态注册路由。Vue Router 4 的动态路由 API 比较成熟配合import.meta.glob实现组件的按需加载既能满足“菜单随客户变”又能保持代码统一// 伪代码根据配置生成菜单和路由 const viewModules import.meta.glob(/src/views/**/*.vue); function buildRoutes(menuConfig) { return menuConfig.map((item) ({ path: item.path, name: item.name, component: viewModules[/src/views/${item.componentPath}.vue] })); }这里要特别提醒一句动态路由的表象虽然灵活但权限控制一定要有后端数据兜底只靠前端隐藏菜单是不安全的。不过这是另一个话题了今天不展开。如果在做多客户配置自动化你至少要把“功能开关”和“菜单路由”两个维度分开前者决定某个能力有没有后者决定用户看到什么入口两者混在一起后期改一处就崩另一处。5.4 本地调试时如何快速切换客户本地开发时你不可能为了看客户 B 的样式去改hosts文件绑定域名。我这里有一个很喜欢的小技巧让resolveSiteName优先解析 URL 参数?__sitecustomerB然后 loader 里再把这个参数自动替换掉不让它进入 Vue Router 的路由记录否则每次刷新路由会多一个 query 黏在 URL 上时间长了你会疯掉。function cleanQuery() { var url win.location.href; if (url.indexOf(__site) -1) { var cleanUrl url.replace(/[?]__site[^]/, ); history.replaceState(null, , cleanUrl); } } cleanQuery();这个“带参调试、进站清参”的处理方式前端同事之间接力联调时特别方便A 同事发给 B 一个链接http://localhost:5173/?__sitecustomerBB 打开直接进入客户 B 的站点配置不用任何手工改动。自动生成站点配置之后最好把npm run generate:site挂到predev和prebuild钩子里保证本地开发和生产构建拿到的配置都是最新生成的。不要问“为什么我改了 tenants.json 跑起来没变化”多半就是忘记先跑一遍生成脚本。最后一个小经验做完这套自动化之后维护成本最大的其实不是代码是tenants.json里的字段越来越多。所以我后来在客户配置里加了一个schemaVersion字段每次字段结构调整都升版本生成的配置里统一写一个版本号自己写了一个简单的校验脚本跑在 CI 里。这样配置漏改、新增字段没补默认值都能第一时间发现。如果你也是一个人维护十几个客户的 Vue 项目我特别推荐把 3.1 到 4.1 的核心链路先搭出来花费的时间一般不超过半天但之后每一周你都会感谢这个半天的投入。如果是一个小团队就让流水线把“配置差异”和“代码发布”彻底分开你会发现发布时的心理压力小一个数量级。以上就是我在多客户配置自动化这条路上摸爬滚打后沉淀下来的完整方案与细节希望对你手头的项目有帮助。