前端开发中 dist 目录详解：概念、配置与部署

所以 dist 的核心特点就是：'可运行、可发布、可部署'。

4. 不同工具里 dist 的默认规则与配置

4.1 Vite：默认 dist/，可用 outDir 修改

vite.config.ts：

import { defineConfig } from "vite";
export default defineConfig({
  build: {
    outDir: "dist", // 输出目录
    assetsDir: "assets", // 静态资源目录
    sourcemap: false, // 是否生成 sourcemap
  },
});

构建命令：

npm run build

4.2 Webpack：通过 output.path 决定输出目录

webpack.config.js：

const path = require("path");
module.exports = {
  output: {
    path: path.resolve(__dirname, "dist"),
    filename: "js/[name].[contenthash].js",
    clean: true, // 构建前清理 dist
  },
};

4.3 Vue CLI：通过 outputDir 配置

vue.config.js：

module.exports = {
  outputDir: "dist",
  assetsDir: "static",
};

4.4 Angular：构建输出也是 dist（但通常带项目名）

常见输出类似：

dist/<project-name>/

5. dist 要不要提交到 Git？（高频问题）

答案：看场景，但大多数情况下不提交。

✅ 一般业务前端项目（网站/管理后台）

• 不提交 dist
• 因为 dist 可由 CI/CD 或本地构建生成
• 提交 dist 会导致仓库膨胀、冲突频繁

建议在 .gitignore 中加入：

dist/

✅ 必须提交 dist 的常见场景

• 你用 GitHub Pages 直接托管构建产物（有时会把产物放到 gh-pages 分支）
• 你发布的是 npm 包，需要包含编译后的产物（通常发布到 npm，而不是提交到 git 主分支）
• 某些历史项目/无构建环境的服务器，只能手动上传 dist

6. dist 与 build 有什么区别？

有的项目叫 dist/，有的叫 build/，本质都指 构建产物，区别通常是'约定俗成'：

• dist：强调'分发/发布（distribution）'
• build：强调'构建过程的结果（build output）'

比如：

• CRA（Create React App）默认 build/
• Vite/Vue CLI 常见 dist/

7. dist 部署实践：你应该怎么用它？

7.1 Nginx 静态部署（最经典）

把 dist 上传到服务器某个目录，例如：

/usr/share/nginx/html/

SPA（单页应用）还要配 history 路由回退：

location / {
  try_files $uri $uri/ /index.html;
}

7.2 CDN + 静态托管

dist 中的 assets 一般带 hash，非常适合 CDN 缓存：

• app.8f3a1c.js（文件名带 hash）
• 更新版本就会变文件名，缓存自然失效

8. 常见坑与排查思路

坑 1：dist 空的 / 没生成

• 检查构建命令是否正确：npm run build
• 看控制台是否报错（依赖缺失、TS 报错、内存不足）
• 确认输出目录没被改到别的名字（如 build/）

坑 2：部署后刷新 404（SPA 常见）

• Nginx/托管平台没做 index.html 回退
• 解决：配置 try_files 或平台的重写规则

坑 3：静态资源路径不对（图片/CSS 404）

• base / publicPath 配错
• 例如部署在子路径 /admin/ 下，需要配置：
  • Vite：base: "/admin/"

坑 4：dist 里 sourcemap 泄露源码

• 生产环境一般关闭 sourcemap
• 或者只对内部环境开放 sourcemap 下载

9. 总结

• dist 是 distribution 的缩写，代表'最终可发布/可部署的产物'
• 前端里 dist 通常是 构建后的静态站点
• 组件库里 dist 常是 编译后的 JS + 类型声明
• Python 里 dist 是 打包后的 wheel/sdist 发布文件
• 多数业务项目 不建议把 dist 提交到 Git，而是交给构建流程生成
• 部署 dist 时重点关注：路由回退（SPA）、资源路径（base/publicPath）、缓存策略（hash）