Vite 中全局常量替换主要通过 define 选项实现，它在构建和开发时静态替换变量为 JSON 序列化值，适用于版本号、API 地址等编译期常量，非运行时读取，不替代 import.meta.env。
在 Vite 中配置全局常量替换，主要通过 define 选项实现。它会在构建和开发服务器启动时，将指定的变量名静态替换为对应值（字符串字面量或 JSON 序列化后的结果），适用于注入环境标识、API 地址、版本号等编译期确定的常量。
使用 define 配置静态常量
Vite 的 define 选项接受一个对象，键为要替换的全局变量名（支持点号嵌套），值为替换后的 JavaScript 字面量（如字符串、布尔值、数字、对象等）。Vite 会将其直接内联到代码中，**不是运行时读取**，也不是环境变量代理。
- 配置写在
vite.config.ts或vite.config.js的define字段中 - 值必须是可被 JSON 序列化的类型；若需字符串，要手动加引号（如
'"prod"'）或用JSON.stringify() - 推荐用
JSON.stringify()避免引号错误，尤其对字符串和对象
示例：
vite.config.tsexport default defineConfig({
define: {
__APP_VERSION__: JSON.stringify('1.2.0'),
__API_BASE__: JSON.stringify('https://api.example.com'),
__IS_DEV__: JSON.stringify(import.meta.env.DEV),
__FEATURE_FLAGS__: JSON.stringify({ enableNewUI: true, debugMode: false })
}
})
之后在任意模块中可直接使用：
立即学习“Java免费学习笔记（深入）”；
console.log(__APP_VERSION__) // "1.2.0" console.log(__API_BASE__) // "https://api.example.com" console.log(__FEATURE_FLAGS__.enableNewUI) // true
注意：define ≠ 环境变量（import.meta.env）
define 是纯文本替换，不经过任何运行时解析；而 import.meta.env 是 Vite 注入的只读对象，其字段受 .env 文件和 envPrefix 控制，且仅限 VITE_ 开头的变量暴露给客户端。
- 不要用
define替代import.meta.env.VITE_API_URL—— 后者更安全、支持热更新、与 .env 集成更好 - 适合用
define的场景：需要在压缩阶段被完全消除的条件分支（如if (__IS_PROD__) { ... }）、无法用import.meta.env表达的复杂常量（如预计算的对象结构） - Terser（生产构建默认压缩器）能自动移除死代码，例如：
if (false) { ... }或if (__DEBUG__ === false) { ... }整块会被删掉
在 TypeScript 中避免类型报错
直接使用未声明的全局变量（如 __APP_VERSION__）会导致 TS 报错。需在 env.d.ts 中补充类型声明：
// src/env.d.ts
declare const __APP_VERSION__: string
declare const __API_BASE__: string
declare const __IS_DEV__: boolean
declare const __FEATURE_FLAGS__: { enableNewUI: boolean; debugMode: boolean }
或者统一声明为 const 类型（推荐）：
declare global {
const __APP_VERSION__: string
const __API_BASE__: string
const __IS_DEV__: boolean
const __FEATURE_FLAGS__: Record<string, any>
}
export {}
结合环境区分定义（可选进阶）
可通过 mode 参数动态设置 define 内容，例如区分 development / production：
export default defineConfig(({ mode }) => ({
define: {
__BUILD_TIME__: JSON.stringify(new Date().toISOString()),
__MODE__: JSON.stringify(mode),
...(mode === 'production' ? {
__ANALYTICS_ID__: JSON.stringify('prod-abc123')
} : {
__ANALYTICS_ID__: JSON.stringify('dev-test999')
})
}
}))
⚠️ 注意：new Date() 在配置阶段执行，每次启动 Vite 服务时生成一次，不是每次请求。
