前端工程化 / 系统课时

规划输出目录与资源命名

规划输出目录与资源命名

本课解决构建产物散乱、误删源码和缓存失效的问题。你将设计独立输出目录,统一脚本、样式与静态资源的命名规则,并通过内容哈希建立可安全长期缓存的发布结构。

学习目标

  • 正确设置 outDir 与 assetsDir,隔离源码和构建产物
  • 使用入口、分块和资源命名规则组织输出文件
  • 配置与文件名匹配的 HTML、CDN 和浏览器缓存策略

先划清输出边界

outDir 应指向专用构建目录,不能与 src、public、项目根目录或人工维护的部署文件混用。生产构建可能清理输出目录;边界不清时,一次正常构建也可能删除不该删除的文件。

assetsDir 是相对于 outDir 的资源子目录,适合统一收纳生成的脚本、样式、字体和图片。目录名称不需要表达版本号,版本变化应交给内容哈希处理,避免每次发布都修改代码中的路径约定。

配置目录与命名规则

下面将所有产物写入 dist/web,并把入口脚本、异步分块和其他资源放入稳定的子目录。文件名保留 [name] 便于排查,加入 [hash] 便于缓存失效。

ts
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    outDir: 'dist/web',
    assetsDir: 'static',
    // 仅在确认该目录完全由构建生成时才允许自动清理
    emptyOutDir: true,
    rolldownOptions: {
      output: {
        entryFileNames: 'static/js/[name]-[hash].js',
        chunkFileNames: 'static/js/[name]-[hash].js',
        assetFileNames: 'static/assets/[name]-[hash][extname]',
      },
    },
  },
})

assetsDir 定义默认资源根目录;一旦进一步设置输出命名模式,就应让模式中的路径与它保持一致。当前规则把 JavaScript 单独放入 static/js,其余 CSS、图片和字体进入 static/assets。

执行构建:

bash
npm run build

预期输出:

text
vite v<VERSION> building for production...
✓ <COUNT> modules transformed.
dist/web/index.html                              <SIZE>
dist/web/static/js/index-<HASH>.js               <SIZE>
dist/web/static/assets/index-<HASH>.css           <SIZE>
✓ built in <TIME>

实际文件数量、名称、哈希、体积和耗时会随入口、动态导入与资源内容变化。验收重点是所有生成文件都位于 dist/web,且长期缓存资源的文件名包含内容哈希。

让目录结构服务缓存

Vite 构建目录、文件命名与缓存策略关系

index.html 通常不带内容哈希,因为它承担最新资源入口的职责,应使用不缓存或短缓存策略。带哈希的 JavaScript、CSS、图片和字体可设置长期缓存;内容改变后文件名随之改变,浏览器会请求新地址。

不要为了得到“固定 URL”而删除所有哈希。入口文件或外部系统确实要求稳定名称时,只对明确的文件单独处理,并确认它不会被长期缓存;否则发布新版本后,用户可能继续命中旧文件。

防止覆盖与发布残留

启用 emptyOutDir 前必须确认输出目录完全由构建系统管理。若部署流程还会把配置、证书占位或人工文件写入同一目录,应改为分目录管理,或先构建到临时目录,再由发布脚本原子替换。

发布时不要只上传新增文件。新的 index.html 可能引用新哈希资源,而旧页面仍可能引用上一版本文件;应保留短暂回滚窗口,或采用版本目录与原子切换,避免动态导入在发布瞬间请求到已删除的旧分块。

验收清单

构建后检查 dist/web 之外没有新增产物,源码目录没有被删除或修改;连续执行两次构建且源码不变时,主要资源哈希应保持稳定;修改一处业务代码后,受影响文件的哈希应变化。

最后检查部署响应头:HTML 能及时重新验证,带哈希资源可以长期缓存,静态服务器能正确返回深层路径和资源 MIME 类型。目录设计、命名规则与缓存头必须作为一套方案共同验收。

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

目录与阅读设置

阅读设置

17

记录一个想法

规划输出目录与资源命名

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

登录哪都通