前端工程化 / 系统课时
完成可维护配置基线
完成可维护配置基线
可维护的 Vite 配置不靠堆叠选项,而是把环境值、通用规则、插件和验证脚本放在清晰边界内。本课完成一份可直接落地的配置入口,并为构建产物增加自动检查,避免配置只在个人电脑上可用。
学习目标
- 建立环境变量、配置代码和业务代码之间的职责边界
- 统一代理、别名、构建与插件的组织方式
- 用诊断脚本验证产物路径和构建清单
明确基线边界
团队基线应只保存稳定规则,环境差异通过 .env.[mode] 注入。开发代理属于本地开发能力,不能假设部署后仍由 Vite 转发;VITE_* 变量会进入客户端产物,只能放公开值,密钥和后端凭据必须留在服务端。
配置入口负责组合规则,不应直接读取业务模块。插件应有明确名称和用途,条件启用逻辑集中处理;别名必须指向绝对文件系统路径;构建目录、资源目录、Source Map 和 manifest 由团队统一约定。

组织配置文件
一个小型团队可以从以下结构开始,等规则增长后再把代理、插件或构建选项拆成独立模块:
project/
├─ src/
├─ scripts/
│ └─ verify-dist.mjs
├─ .env.example
├─ .env.development
├─ .env.production
├─ vite.config.ts
└─ package.json.env.example 只列字段和安全默认值,用于说明团队契约;本地私有覆盖写入 .env.local 并加入忽略列表。模式文件表达部署环境差异,不要用复制多份 vite.config.* 的方式长期分叉。
VITE_BASE=/
VITE_API_TARGET=http://127.0.0.1:3000
VITE_DEV_PORT=5173这些字段会影响公开路径和开发服务器行为,其中 VITE_API_TARGET 仅供开发代理使用。生产环境的真实 API 转发应由网关、反向代理或后端服务配置。
编写统一配置入口
下面的 vite.config.ts 只依赖 Vite 与 Node 内置模块,可作为 Vite 8 项目的最小基线。loadEnv 让模式变量参与配置计算,resolve.tsconfigPaths 启用内置的 TypeScript 路径解析;若团队不使用 tsconfig.json 的 paths,可以关闭该项。
import { fileURLToPath, URL } from 'node:url'
import {
defineConfig,
loadEnv,
type PluginOption,
} from 'vite'
function configSummaryPlugin(): PluginOption {
return {
name: 'team-config-summary',
configResolved(config) {
// 构建日志只输出非敏感配置,便于 CI 留档和排障
console.log(
`[vite-config] mode=${config.mode} base=${config.base}`,
)
},
}
}
export default defineConfig(({ command, mode }) => {
const env = loadEnv(mode, process.cwd(), 'VITE_')
const isBuild = command === 'build'
return {
base: env.VITE_BASE || '/',
plugins: [configSummaryPlugin()],
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
tsconfigPaths: true,
},
server: {
port: Number(env.VITE_DEV_PORT || 5173),
strictPort: true,
proxy: {
'/api': {
target: env.VITE_API_TARGET || 'http://127.0.0.1:3000',
changeOrigin: true,
},
},
},
build: {
outDir: 'dist',
assetsDir: 'assets',
sourcemap: isBuild ? 'hidden' : false,
manifest: true,
emptyOutDir: true,
},
preview: {
port: 4173,
strictPort: true,
},
}
})启动或构建时,日志会显示最终模式与 base。hidden Source Map 会生成映射文件但不在产物中写入引用注释,是否上传到线上应由错误监控和发布策略决定;manifest: true 会生成构建映射,便于诊断或服务端集成。
加入产物诊断脚本
配置能被加载不代表产物一定符合部署约定。下面的脚本检查 index.html 中的根绝对资源是否遵守预期 base,并确认 manifest 已生成。它不会替代浏览器端 E2E,但能在 CI 中提前拦截常见路径错误。
import { access, readFile } from 'node:fs/promises'
import { resolve } from 'node:path'
const distDir = resolve('dist')
const expectedBase = process.env.EXPECTED_BASE || '/'
const html = await readFile(resolve(distDir, 'index.html'), 'utf8')
const localRefs = [...html.matchAll(/(?:src|href)=["']([^"']+)["']/g)]
.map((match) => match[1])
.filter((url) => !url.startsWith('http') && !url.startsWith('data:'))
const invalidRefs = localRefs.filter(
(url) => url.startsWith('/') && !url.startsWith(expectedBase),
)
if (invalidRefs.length > 0) {
throw new Error(`资源路径未匹配 ${expectedBase}: ${invalidRefs.join(', ')}`)
}
await access(resolve(distDir, '.vite', 'manifest.json'))
console.log(`[verify-dist] base=${expectedBase}`)
console.log(`[verify-dist] localRefs=${localRefs.length}`)
console.log('[verify-dist] manifest=ok')构建并执行验证:
npm run build
EXPECTED_BASE=/ node scripts/verify-dist.mjs预期输出
[vite-config] mode=production base=/
[verify-dist] base=/
[verify-dist] localRefs=<COUNT>
[verify-dist] manifest=ok资源数量和构建耗时会因项目而异。部署在子路径时,把命令中的 EXPECTED_BASE 改成与 VITE_BASE 一致的值,例如 /app/。
团队验收清单
合并配置变更前,至少验证开发启动、生产构建和产物诊断三条路径。代理目标不可写死为个人地址;别名在编辑器、TypeScript 与 Vite 中应保持一致;新增插件要说明应用阶段、顺序要求和关闭方式;修改 base、输出目录或缓存策略时,应同步更新部署配置与验收命令。
CI 应使用锁文件安装依赖,并保存构建日志。配置升级时先阅读迁移说明,再在独立分支验证,不要把工具链主版本升级与业务功能改动混在同一次提交中。