Vite Mode 与环境选择
区分 Vite mode 与 NODE_ENV，说明环境选择、字符串开关及 Nx 配置映射的边界。
[!info] related notes
- 所属：Vite 基础 MOC
- 环境变量规则：加载优先级与客户端暴露
- Nx 联调：Nx 与 Vite 环境变量冲突
Vite Mode 与环境选择
Mode 是 Vite 的环境名称，决定加载哪组环境文件，也可供配置函数选择配置。它与 NODE_ENV 独立：vite build --mode staging 默认仍是生产构建；名为 staging 的 mode 不会自动打开 sourcemap、代理或关闭压缩。
1. 为什么会出现 Mode？（解决什么痛点）
在 Mode 概念成熟之前，开发者通常依赖 process.env.NODE_ENV 来区分开发和生产环境。但随着项目复杂化，这种方式暴露了几个缺陷：
- 二元对立的局限性：只有 “development” 和 “production” 远远不够。现实中我们有：本地开发、内网测试（Staging）、灰度发布（Preview）、正式生产等多个阶段。
- 配置硬编码：如果没有 Mode 系统，开发者可能需要在代码里写大量的
if/else来切换 API 地址，这极易导致发布时漏改配置。 - 构建优化需求不同：测试环境可能需要开启 SourceMap 方便排查问题，而生产环境则需要彻底压缩代码并移除调试日志。
Vite 引入 Mode 机制，就是为了将“环境标识”与“构建配置/环境变量”解耦，让开发者可以自由定义任何环境。
2. Vite Mode 的核心工作机制
Mode 的本质是一个指令开关。当你运行 Vite 命令时，可以显式指定它：
vite --mode staging- 在 Nx 中，可在 executor 支持的 options/configurations 中显式传递 mode；configuration 名称不保证自动成为 Vite mode。
环境文件加载逻辑
Vite dev 默认 mode 为 development，build 默认为 production，可用 --mode staging 覆盖。环境文件的完整优先级、进程变量覆盖与 VITE_ 暴露规则统一见 vite-env-and-import-meta-env，避免这里维护第二份加载规则。配置函数中读取 env 需按 mode 调用 loadEnv。
3. Mode 的主要应用场景
Mode 目前在项目中主要用于以下四个维度：
A. 动态 API 地址转发（最常用）
客户端可读取 VITE_API_BASE_URL 选择 API 根地址；若采用 server.proxy，客户端应请求同源 /api，代理目标则由配置函数读取 env 后设置。二者不会自动联动。
- 开发模式：连
localhost:3000。 - Staging 模式：连测试服务器，方便与后端同事联调未上线的接口。
B. 功能开关 (Feature Toggles)
你可以定义 VITE_ENABLE_NEW_UI=true。
- 在代码中通过
if (import.meta.env.VITE_ENABLE_NEW_UI === 'true')来控制新功能是否对用户可见。 - env 自定义变量是字符串，
"false"本身仍是真值。此开关可控制界面分支，不是访问控制，后端仍应校验权限。
C. 条件式代码注入
有时候你只想在测试环境引入调试工具（如 vConsole 或 eruda）：
if (import.meta.env.MODE === 'staging') {
import('vconsole').then(({ default: VConsole }) => new VConsole());
}Vite 在打包时会识别这些条件。在启用相应优化的 production mode 构建中，条件为假时这条分支可被移除；如果其他位置仍引用同一依赖，依赖不一定从产物消失，应查看构建结果。
D. 静态资源 CDN 路径
在 project.json 中，你可以为不同的模式配置不同的 base 路径：
- Staging: 放在服务器子目录下，如
/test-app/。 - Production: 使用 CDN 地址，如
https://static.cdn.com/assets/。
4. 在 Nx 环境下操作 Mode 的进阶技巧
Nx 的 configuration 是一组任务选项，Vite mode 是其中可能传递的一项，二者需显式映射。多个服务协同启动由 Nx target / dependsOn 等任务配置负责，不是 mode 本身的功能。
缓存是否能区分环境，取决于实际传入的任务参数及 Nx inputs/env 设置；不能只凭 configuration 名称断言缓存正确。联调时核对最终 mode、API 目标和缓存输入，避免 Nx 提前加载的进程环境覆盖 Vite 文件。
学习检查
vite build --mode staging是否自动关闭生产优化？.env.production中写VITE_ENABLE_NEW_UI=false，为何直接用于 if 仍进入分支？
参考答案
- 不会。mode 选择环境名称，默认生产构建的 NODE_ENV 仍是 production；其他配置须显式决定。
- 读取到字符串
"false"，应比较=== 'true'或自行解析验证。
Digital Biome