前端工程化 / 系统课时

完成可维护配置基线

完成可维护配置基线

可维护的 Vite 配置不靠堆叠选项,而是把环境值、通用规则、插件和验证脚本放在清晰边界内。本课完成一份可直接落地的配置入口,并为构建产物增加自动检查,避免配置只在个人电脑上可用。

学习目标

  • 建立环境变量、配置代码和业务代码之间的职责边界
  • 统一代理、别名、构建与插件的组织方式
  • 用诊断脚本验证产物路径和构建清单

明确基线边界

团队基线应只保存稳定规则,环境差异通过 .env.[mode] 注入。开发代理属于本地开发能力,不能假设部署后仍由 Vite 转发;VITE_* 变量会进入客户端产物,只能放公开值,密钥和后端凭据必须留在服务端。

配置入口负责组合规则,不应直接读取业务模块。插件应有明确名称和用途,条件启用逻辑集中处理;别名必须指向绝对文件系统路径;构建目录、资源目录、Source Map 和 manifest 由团队统一约定。

可维护 Vite 配置基线的分层结构

组织配置文件

一个小型团队可以从以下结构开始,等规则增长后再把代理、插件或构建选项拆成独立模块:

text
project/
├─ src/
├─ scripts/
│  └─ verify-dist.mjs
├─ .env.example
├─ .env.development
├─ .env.production
├─ vite.config.ts
└─ package.json

.env.example 只列字段和安全默认值,用于说明团队契约;本地私有覆盖写入 .env.local 并加入忽略列表。模式文件表达部署环境差异,不要用复制多份 vite.config.* 的方式长期分叉。

bash
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,可以关闭该项。

ts
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 中提前拦截常见路径错误。

js
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')

构建并执行验证:

bash
npm run build
EXPECTED_BASE=/ node scripts/verify-dist.mjs

预期输出

text
[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 应使用锁文件安装依赖,并保存构建日志。配置升级时先阅读迁移说明,再在独立分支验证,不要把工具链主版本升级与业务功能改动混在同一次提交中。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

完成可维护配置基线

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通