Vite 环境变量与静态资源

环境变量

定义（根目录 env 文件）

# .env.development
VITE_API_URL=http://localhost:3000
VITE_APP_TITLE=博客系统(开发)

# .env.production
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=博客系统

只有 VITE_ 前缀的变量才会暴露给客户端代码，避免误泄露服务端密钥。自定义前缀需配置 envPrefix。

使用

// 客户端代码中通过 import.meta.env 访问
console.log(import.meta.env.VITE_API_URL);
console.log(import.meta.env.MODE);     // 当前模式：development / production
console.log(import.meta.env.DEV);      // 是否开发环境
console.log(import.meta.env.PROD);     // 是否生产环境

<!-- index.html 中使用（构建时替换） -->
<title><%- VITE_APP_TITLE %></title>

TypeScript 类型提示

src/env.d.ts：

/// <reference types="vite/client" />

interface ImportMetaEnv {
	readonly VITE_API_URL: string;
	readonly VITE_APP_TITLE: string;
}

interface ImportMeta {
	readonly env: ImportMetaEnv;
}

静态资源处理

两种引用方式

// 1. src/assets：作为模块导入，构建后带 hash 文件名，小于 4kb 转为 base64 内联
import logo from "@/assets/logo.png";
<img :src="logo" />;

// 2. public 目录：不参与构建，原样拷贝到 dist，必须用绝对路径引用
<img src="/logo.png" />;

new URL 方式（适合动态拼接）

const imgUrl = new URL(`./assets/${name}.png`, import.meta.url).href;

CSS 引入

// scss 中使用别名需要加 ~ 前缀（老版本）或直接用别名
@use "@/styles/variables.scss" as *;

// 引入图片
.logo {
	background: url("@/assets/logo.png") no-repeat center;
}

glob 批量导入

// 动态导入某目录下所有模块（路由自动注册常用）
const modules = import.meta.glob("./modules/*.ts"); // 懒加载：返回 () => import()
for (const path in modules) {
	modules[path]().then(mod => {
		console.log(path, mod.default);
	});
}

// 立即加载
const mods = import.meta.glob("./modules/*.ts", { eager: true });

常见问题

1. 导入 .vue 报错找不到模块：确认安装了 @vitejs/plugin-vue 并在 plugins 中注册，env.d.ts 中保留 /// <reference types="vite/client" />
2. scss 全局变量不生效：使用 css.preprocessorOptions.scss.additionalData 注入，而不是在组件里反复 import
3. dev 请求后端接口跨域：配置 server.proxy，让请求先发给 vite dev server