生产环境最佳实践专题

专题说明

本专题介绍 Vite 生产环境部署的最佳实践，帮助开发者优化部署流程与监控体系。

学习目标

1. 掌握 CDN 部署与资源分发策略
2. 理解安全策略配置方法
3. 学会 CI/CD 构建流水线优化与性能监控集成

学习内容

• CDN 部署与资源分发：静态资源 CDN 配置
• 安全策略配置：CSP、HTTPS 策略
• CI/CD 构建流水线优化：构建缓存与并行
• 构建产物版本管理：产物版本化策略与回滚机制
• 性能监控集成：构建产物监控与告警

学习建议

实际配置生产环境部署流程，集成性能监控体系。

构建产物版本管理

构建产物的版本化管理是生产环境部署中的关键环节，直接影响灰度发布、快速回滚和问题追溯能力。Vite 本身不内置版本管理，但可以通过构建配置与 CI/CD 流程集成，实现可靠的产物版本化策略。

核心策略

1. 版本号注入：将版本标识（Git commit hash、CI 构建号、语义版本号）注入到构建产物的文件名或目录结构中。
2. Manifest 映射：利用 Vite 生成的 manifest 文件建立版本与产物的映射关系，支持多版本并存。
3. 版本化部署目录：以版本号作为部署目录名，实现原子化切换与秒级回滚。

获取 Git 版本信息

通过 Node.js 脚本在构建时读取 Git 信息，注入到环境变量中：

// scripts/get-version.js
import { execSync } from 'child_process';

const GIT_COMMIT_HASH = execSync('git rev-parse --short HEAD').toString().trim();
const GIT_BRANCH = execSync('git rev-parse --abbrev-ref HEAD').toString().trim();
const BUILD_TIME = new Date().toISOString();

process.stdout.write(JSON.stringify({
  GIT_COMMIT_HASH,
  GIT_BRANCH,
  BUILD_TIME,
}));

Vite 配置中注入版本号

// vite.config.ts
import { defineConfig, loadEnv } from 'vite';
import { execSync } from 'child_process';

function getBuildVersion() {
  const hash = execSync('git rev-parse --short HEAD').toString().trim();
  const time = new Date().toISOString().replace(/[:.]/g, '-');
  return `${time}-${hash}`;
}

export default defineConfig(({ mode }) => {
  const BUILD_VERSION = getBuildVersion();

  return {
    define: {
      __BUILD_VERSION__: JSON.stringify(BUILD_VERSION),
      __BUILD_TIME__: JSON.stringify(new Date().toISOString()),
    },

    build: {
      // 以版本号作为静态资源子目录
      assetsDir: `assets/${BUILD_VERSION}`,

      rollupOptions: {
        output: {
          // 入口文件携带版本号便于多版本共存
          entryFileNames: `js/[name]-${BUILD_VERSION}.js`,
          chunkFileNames: `js/[name]-${BUILD_VERSION}.js`,
          assetFileNames: `assets/[name]-${BUILD_VERSION}.[ext]`,
        },
      },
    },
  };
});

运行时版本暴露

<!-- index.html -->
<script>
  window.__APP_VERSION__ = '<%= BUILD_VERSION %>';
</script>

配合 Vite 的 transformIndexHtml 钩子替换模板变量：

// vite.config.ts 中追加
plugins: [
  {
    name: 'html-version-inject',
    transformIndexHtml(html) {
      return html.replace(/<%= BUILD_VERSION %>/g, BUILD_VERSION);
    },
  },
],

构建产物版本化目录结构示例

dist/
├── v2026-06-02T10-30-00Z-a1b2c3d/
│   ├── index.html
│   ├── assets/
│   │   └── v2026-06-02T10-30-00Z-a1b2c3d/
│   └── js/
├── v2026-06-01T18-00-00Z-d4e5f6g/
│   ├── index.html
│   ├── assets/
│   └── js/
└── current -> v2026-06-02T10-30-00Z-a1b2c3d/   # 软链接指向当前版本

Manifest 版本记录

Vite 构建默认生成 manifest.json，记录了所有产物文件的映射关系。在多版本部署场景中，应保留每个版本的 manifest 用于问题追溯：

// vite.config.ts
build: {
  manifest: true,
},

部署时将该文件与产物一同归档到版本目录，方便回滚后快速确认产物版本状态。

版本管理注意事项

• 构建时环境一致性：Git hash 依赖 .git 目录存在，Docker 构建时需通过 .dockerignore 保留或通过 CI 环境变量传入。
• 产物命名长度：过长的版本字符串可能导致文件系统路径超限，建议使用短 hash（--short）并控制前缀长度。
• 静态资源 CDN 缓存：版本化文件名天然支持缓存更新（内容变化 → 文件名变化 → CDN 自动拉取新文件），无需额外配置缓存策略。
• 多版本并存清理：建议在 CI/CD 中设置产物保留策略（如保留最近 N 个版本），避免磁盘空间持续增长。