Vite 8 前端工程实战：环境变量、构建与部署检查

前端项目“本地正常、上线白屏”通常不是神秘问题，而是环境变量、基础路径或静态资源部署不一致。本文把 Vite 的构建过程拆成可验证步骤。

一、理解 mode 与 NODE_ENV 的区别

Vite 命令可通过 --mode 选择环境文件。常见文件如下：

.env                 # 所有模式
.env.local           # 本机覆盖，不提交
.env.staging         # staging 模式
.env.staging.local   # staging 本机覆盖，不提交
.env.production      # production 模式

只有以 VITE_ 开头的变量默认暴露给客户端代码。这不是保密机制：进入前端产物的值都能被访问者读取，因此数据库密码、私钥和服务端令牌绝不能放入其中。

二、配置并验证公开变量

# .env.staging
VITE_API_BASE_URL=https://staging-api.example.com
VITE_APP_ENV=staging

const apiBaseUrl = import.meta.env.VITE_API_BASE_URL

if (!apiBaseUrl) {
  throw new Error('VITE_API_BASE_URL is required')
}

export { apiBaseUrl }

在应用入口尽早校验必需配置，比请求发出后才出现模糊的网络错误更容易定位。

三、分别构建不同模式

npm run build -- --mode staging
npm run build -- --mode production
npm run preview

vite preview 只用于本地检查构建产物，不是生产服务器。预览时至少验证首页刷新、深层路由、API 请求和静态资源加载。

四、子路径部署时设置 base

import { defineConfig } from 'vite'

export default defineConfig({
  base: '/docs/',
})

如果站点部署在域名根路径，保留默认 /。如果部署在 /docs/，构建配置、Web 服务器路径与前端路由基路径必须一致。

五、构建后检查，而不是只看退出码

npm run build
find dist -maxdepth 2 -type f | sort
grep -R "PRIVATE_KEY\|DB_PASSWORD" dist || true

确认 dist/index.html 引用的资源真实存在。
确认构建产物中没有密钥或内部凭据。
在浏览器 Network 面板检查 JS/CSS 是否 200，Content-Type 是否正确。
直接访问一个前端路由并刷新，确认服务器回退到 index.html。

六、推荐部署顺序

锁定依赖并运行测试。
校验目标 mode 的环境变量。
生成带版本号的新产物目录。
在临时地址进行冒烟测试。
原子切换静态目录或 CDN 版本。
保留上一版本，以便快速回滚。

常见问题

变量是 undefined

检查前缀、mode、文件名和开发服务器是否重启。环境文件变化后应重新启动 Vite。

页面打开但资源 404

检查 base 与实际部署子路径，不要用硬编码绝对路径绕过问题。

上线后仍是旧页面

检查 HTML 缓存、CDN 缓存和 Service Worker。带 hash 的资源可长缓存，入口 HTML 通常应更快更新。