vite build如何排除指定目录不打包？

Question

在使用 Vite 构建项目时，如何排除指定目录（如 `mocks/` 或 `tests/`）不参与打包？尽管这些目录未被主入口引用，但在某些配置下仍可能被误引入或出现在输出目录中。希望通过 vite.config.js 配置或插件机制实现构建时自动忽略特定文件夹，确保打包结果更干净、体积更小。常见的尝试包括调整 rollupOptions.external 或使用 .gitignore，但效果不佳。该如何正确配置？

Answer 1

1. 问题背景与常见误区

在使用 Vite 构建前端项目时，开发者常期望将 mocks/、tests/ 等非生产目录排除在最终打包结果之外。尽管这些目录未被主入口文件（如 main.ts 或 index.html）显式引用，但在某些配置下仍可能被 Rollup 打包器自动扫描并输出到 dist/ 目录中。

常见的尝试包括：

• 设置 rollupOptions.external —— 仅影响模块解析，不阻止文件拷贝；
• 依赖 .gitignore —— Vite 构建系统并不读取该文件来决定构建行为；
• 手动删除输出目录中的文件 —— 不可持续且易出错。

因此，需要更精准的机制从构建流程层面排除指定目录。

2. Vite 构建机制解析

Vite 基于 Rollup 进行生产构建，其构建流程包含以下关键阶段：

1. 入口发现：从 index.html 开始解析依赖图；
2. 模块加载：通过插件链处理不同类型的模块；
3. 静态资源处理：图片、JSON、字体等被复制或内联；
4. Rollup 打包：生成 chunk 并输出到目标目录；
5. 静态文件拷贝：部分未被引用的资源也可能被复制。

其中，mocks/ 和 tests/ 可能因以下原因进入输出目录：

原因	说明
动态导入匹配	import.meta.glob('./mocks/*.js') 会主动引入整个目录
公共目录（publicDir）	若 mocks 放入 public/，则默认全部拷贝
Rollup 自动收集资源	某些插件或配置导致非引用文件也被视为资源

3. 核心解决方案：vite.config.js 配置策略

正确配置应结合 build.rollupOptions 与 plugins 实现细粒度控制。以下是推荐方案：

import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  build: {
    rollupOptions: {
      // 方法一：external 排除模块解析（适用于防止打包 JS 模块）
      external: [
        /mocks\//,
        /tests\//
      ],
      // 方法二：output.manualChunks 控制 chunk 生成逻辑
      output: {
        // 过滤掉不需要的 chunk
        assetFileNames: (assetInfo) => {
          if (/mocks|tests/.test(assetInfo.name)) {
            return 'assets/skipped/_excluded'; // 引导至无效路径
          }
          return 'assets/[name]-[hash][extname]';
        },
      },
    },
  },
});

注意：external 仅阻止模块执行，但不会阻止静态资源拷贝。

4. 插件级控制：自定义 Rollup 插件实现精确过滤

为彻底排除特定目录，可编写自定义插件，在构建早期阶段拦截文件处理。

function excludeDirsPlugin(dirs = ['mocks', 'tests']) {
  const regex = new RegExp(`^(${dirs.join('|')})[/\\\\]`);
  
  return {
    name: 'exclude-dirs',
    enforce: 'pre',
    resolveId(id) {
      const resolved = this.resolve(id);
      if (resolved && regex.test(path.relative(process.cwd(), resolved.id))) {
        return false; // 告诉 Rollup 忽略该模块
      }
    },
    load(id) {
      if (regex.test(path.relative(process.cwd(), id))) {
        return ''; // 返回空内容，避免报错
      }
    }
  };
}

在 vite.config.js 中启用：

plugins: [excludeDirsPlugin(['mocks', 'tests'])]

5. 公共资源与静态文件的特殊处理

若 mocks/ 被置于 public/ 目录，默认会被完整复制。可通过重写 publicDir 并使用条件拷贝规避：

import fs from 'fs-extra';
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    outDir: 'dist',
    emptyOutDir: true,
    rollupOptions: {
      input: 'index.html',
    },
    // 自定义构建后处理
    copyPublicDir: false, // 关闭默认 public 拷贝
  },
  plugins: [
    {
      name: 'conditional-public-copy',
      async closeBundle() {
        const publicDir = path.resolve(__dirname, 'public');
        const targetDir = path.resolve(__dirname, 'dist');
        if (await fs.pathExists(publicDir)) {
          const entries = await fs.readdir(publicDir);
          for (const item of entries) {
            if (!['mocks', 'tests'].includes(item)) {
              await fs.copy(
                path.join(publicDir, item),
                path.join(targetDir, item)
              );
            }
          }
        }
      }
    }
  ]
});

6. 流程图：构建排除逻辑决策路径

graph TD A[开始构建] --> B{是否引用 mocks/tests?} B -- 否 --> C[检查 glob 导入模式] C --> D{存在 import.meta.glob 匹配?} D -- 是 --> E[修改 glob 模式排除目录] D -- 否 --> F{是否位于 public/?} F -- 是 --> G[禁用 copyPublicDir 并自定义拷贝] F -- 否 --> H[应用 excludeDirsPlugin 插件] H --> I[构建完成，目录已排除] E --> I G --> I

7. 最佳实践建议与扩展思考

为确保长期可维护性，建议采用如下综合策略：

• 统一约定开发目录结构，避免敏感目录与资源目录混杂；
• 使用 import.meta.glob 时明确排除测试与 mock 文件；
• 通过 CI/CD 添加构建产物审计步骤，检测异常文件残留；
• 结合 ESLint 规则禁止在生产代码中引用 mocks/ 或 tests/；
• 利用 TypeScript 的 paths 映射隔离开发辅助模块；
• 对大型项目启用 build.reportCompressedSize 监控体积变化；
• 定期审查 dist/ 输出内容，建立自动化校验脚本；
• 文档化构建排除规则，供团队成员遵循；
• 考虑使用 vite-plugin-inspect 分析依赖图谱；
• 探索基于 conditions 的环境感知构建策略。