vite v4.4.9 默认build输出路径如何配置？

Question

在使用 Vite v4.4.9 构建项目时，如何配置默认的 build 输出路径？默认情况下，Vite 将构建产物输出到 `dist` 目录，但实际项目中常需自定义输出目录。通过 `vite.config.js` 中的 `build.outDir` 选项可修改输出路径，例如设置为 `outDir: 'build'` 可将输出目录改为 `build`。该配置是否支持相对路径或绝对路径？是否会受工作目录影响？如何与 `base` 配合正确处理资源引用？这是开发者常遇到的问题。

Answer 1

1. Vite 构建输出路径配置基础概念

在使用 Vite v4.4.9 构建项目时，默认的构建产物输出目录为 dist。该行为由 vite.config.js 中的 build.outDir 配置项控制。开发者可通过修改此选项来自定义输出路径，例如：

export default {
  build: {
    outDir: 'build' // 输出到项目根目录下的 build 目录
  }
}

这一配置适用于大多数现代前端项目，尤其在 CI/CD 流程中需与部署系统约定输出目录名称时尤为重要。

2. 支持的路径类型：相对路径 vs 绝对路径

outDir 配置支持两种路径格式：

• 相对路径：相对于当前工作目录（通常是项目根目录）解析，如 'build'、'./output'。
• 绝对路径：可直接指向文件系统任意位置，如 /var/www/html/app 或 C:\\projects\\myapp\\dist。

示例配置如下：

export default {
  build: {
    outDir: '/absolute/path/to/output', // Linux/macOS
    // outDir: 'D:\\project\\dist'       // Windows
  }
}

无论使用哪种路径类型，Vite 均会自动创建目标目录及其父级目录（若不存在）。

3. 工作目录的影响机制分析

当使用相对路径时，outDir 的解析依赖于 Node.js 的当前工作目录（process.cwd()），而非 vite.config.js 文件所在目录。这意味着：

启动方式	工作目录	实际输出路径
npm run build	项目根目录	预期路径
node scripts/build.js（从子目录运行）	子目录	可能偏离预期

为避免歧义，建议在脚本中显式设置工作目录或使用基于 __dirname 的绝对路径计算：

import { resolve } from 'path'

export default {
  build: {
    outDir: resolve(__dirname, 'custom-dist')
  }
}

4. 与 base 配置的协同作用

base 配置决定资源引用的公共前缀（即 HTML 中的 <base href=""> 和静态资源路径前缀）。它与 outDir 虽无直接关联，但在部署场景下必须协同配置。

常见组合场景如下：

1. 本地开发：base: '/', outDir: 'dist'
2. 部署至子路径（如 GitHub Pages）：base: '/my-app/', outDir: 'dist'
3. 静态服务器根目录部署：base: '/', outDir: 'public'

错误配置可能导致资源 404，例如：

<script src="/assets/index.123.js"></script>

5. 实际工程中的最佳实践流程图

graph TD A[开始构建] --> B{是否自定义输出路径?} B -- 是 --> C[配置 build.outDir] B -- 否 --> D[使用默认 dist] C --> E{路径为相对还是绝对?} E --> F[相对路径: 依赖 process.cwd()] E --> G[绝对路径: 系统级定位] F --> H[确保 cwd 正确] G --> I[验证权限与存在性] H --> J[结合 base 设置资源前缀] I --> J J --> K[执行 vite build]

6. 多环境动态配置策略

在大型项目中，常需根据环境变量动态设置 outDir。可通过以下方式实现：

const getOutDir = () => {
  switch (process.env.NODE_ENV) {
    case 'development': return 'dev-dist'
    case 'staging': return '/tmp/staging-build'
    case 'production': return '/var/www/prod'
    default: return 'dist'
  }
}

export default {
  base: process.env.BASE_URL || '/',
  build: {
    outDir: getOutDir()
  }
}

该模式增强了构建系统的灵活性，适配复杂部署拓扑。