环境与应用配置

BBC 8.0 前端使用 Vite 环境文件和 packages/config 统一管理三端配置。API 地址、页面域名、部署子路径、静态资源前缀和功能开关都不应硬编码在页面中。

配置来源与优先级

配置按以下顺序读取，前者优先：

Shell、CI 或 Jenkins 注入的当前进程环境变量。
当前 Vite 模式加载的 .env.*.local 和 .env.*。
根目录 config/*.ts 中的仓库默认值。

Vite 构建配置使用 { ...loadEnv(...), ...process.env } 合并变量，因此流水线进程变量会覆盖环境文件。排查构建结果时先确认 CI 实际注入了哪些变量，但不要在日志中回显敏感值。

配置读取入口位于 packages/config：

配置	默认值	读取入口
API 地址	`config/api.ts`	`packages/config/api.ts`
页面域名	`config/domain.ts`	`packages/config/domain.ts`
部署子路径	`config/alias.ts`	`packages/config/alias.ts`
静态资源前缀	`config/assets.ts`	`packages/config/assets.ts`
功能开关	`config/features.ts`	`packages/config/features.ts`
应用名称与标题	无独立根配置	`packages/config/apps.ts`

环境文件与构建模式

仓库跟踪以下三个环境文件：

文件	Vite 模式	对应命令
`.env.development`	`development`	`pnpm dev:`、`pnpm build:dev:`
`.env.test`	`test`	`pnpm build:test:*`
`.env.production`	`production`	`pnpm build:*`

本机联调配置写入 .env.development.local，例如：

VITE_API_GATEWAY=http://localhost:8080
VITE_DOMAIN_PC=http://localhost:3000
VITE_DOMAIN_MOBILE=http://localhost:3001
VITE_DOMAIN_SELLER=http://localhost:3002
VITE_DOMAIN_ADMIN=http://localhost:3003

.local 文件只用于本机，不要提交。环境文件修改后必须重新启动开发服务或重新构建，Vite 不会在已生成的静态文件中动态读取新值。

API 地址

变量	说明
`VITE_API_GATEWAY`	统一网关；设置后会作为未单独配置 API 的回退地址。
`VITE_API_BASE`	基础服务 API。
`VITE_API_BUYER`	买家业务 API。
`VITE_API_SELLER`	商家业务 API。
`VITE_API_ADMIN`	平台管理业务 API。

可以只配置统一网关：

VITE_API_GATEWAY=https://api.example.com

也可以分别配置：

VITE_API_BASE=https://base-api.example.com
VITE_API_BUYER=https://buyer-api.example.com
VITE_API_SELLER=https://seller-api.example.com
VITE_API_ADMIN=https://admin-api.example.com

packages/config/api.ts 会清理尾部斜杠。当前构建快照没有启用完整性强制检查，缺失地址更可能在浏览器启动或实际读取配置时抛错，而不是自动让 Vite 构建失败。因此 CI 和发布流程必须在构建前显式校验目标环境的 API 配置，不能依赖页面运行时报错，也不要补临时域名。

页面域名

变量	说明
`VITE_DOMAIN_PC`	买家 PC 端访问域名。
`VITE_DOMAIN_MOBILE`	买家移动端访问域名，用于跨端跳转。
`VITE_DOMAIN_SELLER`	商家端访问域名。
`VITE_DOMAIN_ADMIN`	平台管理端访问域名。

页面域名由 getDomain() 或 getRuntimeDomain() 读取，主要用于跨端链接。它们与 Vite base 不是同一概念：域名决定跳到哪个站点，base 决定当前应用部署在站点的哪个子路径。

import { getRuntimeDomain } from "@shop-tnt/config";

const domains = getRuntimeDomain(import.meta.env.MODE);
const pcUrl = domains.pc;

部署子路径

变量	说明
`VITE_BASE_PC`	买家 PC 端的 Vite base。
`VITE_BASE_SELLER`	商家端的 Vite base。
`VITE_BASE_ADMIN`	平台管理端的 Vite base。

值会被归一化为不带首尾斜杠的名称。比如：

VITE_BASE_SELLER=seller

构建后的访问路径为 https://example.com/seller/。三端使用独立域名时通常留空。该配置同时影响 Vite 资源路径和 Vue Router history base，修改后必须验证深层 URL 刷新。

静态资源前缀

变量	说明
`VITE_ASSETS_PC`	买家 PC 静态资源 CDN 或前缀。
`VITE_ASSETS_SELLER`	商家端静态资源 CDN 或前缀。
`VITE_ASSETS_ADMIN`	平台管理端静态资源 CDN 或前缀。

不使用 CDN 时留空。使用 CDN 时填写完整公开前缀：

VITE_ASSETS_PC=https://cdn.example.com/shop-tnt/pc/
VITE_ASSETS_SELLER=https://cdn.example.com/shop-tnt/seller/
VITE_ASSETS_ADMIN=https://cdn.example.com/shop-tnt/admin/

packages/config/build/vite.ts 会在构建期改写静态资源 URL。发布后应检查入口 HTML、JavaScript、CSS、字体和图片是否都能从该前缀返回 200。

功能开关

变量	功能
`VITE_DISTRIBUTION`	分销相关页面与路由。
`VITE_I18N`	国际化入口及字典相关页面。
`VITE_IM`	客服与站内 IM。
`VITE_LIVEVIDEO`	直播相关页面与路由。

环境变量支持以下布尔值：

开启：1、true、yes、y、on。
关闭：0、false、no、n、off。

无法识别的值会回退到 config/features.ts。当前路由消费范围如下：

应用	参与路由或入口控制的开关
Admin	分销、直播、IM、国际化
Seller	直播、IM
PC	分销、IM

其它页面仍可能在业务内部读取功能开关。隐藏菜单不等于授权校验，不能只处理视觉入口。

在代码中读取配置

业务代码优先从 @shop-tnt/config 的公开入口导入，不要直接读取根配置文件：

import { getApi, getFeatureFlags, getRuntimeDomain } from "@shop-tnt/config";

const api = getApi(import.meta.env.MODE);
const domains = getRuntimeDomain(import.meta.env.MODE);
const features = getFeatureFlags();

只有 Vite 和配置包内部需要直接处理 import.meta.env。页面不应自行实现环境优先级、尾斜杠清理或布尔值解析。

安全要求

所有 VITE_* 变量都会进入浏览器产物，任何访问者都能读取。禁止写入：

数据库密码、私钥和对象存储密钥。
服务端 token、管理员 token 或长期令牌。
只允许后端持有的第三方应用密钥。
个人信息或其他敏感业务数据。

需要保密的配置必须由后端持有，并通过受控接口提供必要结果。

修改后的验证

本机开发配置只影响单端时，构建对应应用：

pnpm build:dev:pc
pnpm build:dev:seller
pnpm build:dev:admin

修改 packages/config、根 config 或多个应用的环境配置时，构建三端：

pnpm build:dev

验收时至少确认：

四类 API 地址都能正确解析，缺失配置不会被页面静默兜底。
登录、刷新 token 和公开接口分别请求到正确服务。
跨端链接使用配置域名，而不是当前页面硬编码。
子路径部署下首页、深层路由和静态资源都可刷新访问。
功能关闭后，菜单、路由直达和业务入口都被正确限制。

环境与应用配置

配置来源与优先级​

环境文件与构建模式​

API 地址​

页面域名​

部署子路径​

静态资源前缀​

功能开关​

在代码中读取配置​

安全要求​

修改后的验证​