前端工程化 / 系统课时
规划输出目录与资源命名
规划输出目录与资源命名
本课解决构建产物散乱、误删源码和缓存失效的问题。你将设计独立输出目录,统一脚本、样式与静态资源的命名规则,并通过内容哈希建立可安全长期缓存的发布结构。
学习目标
- 正确设置
outDir与assetsDir,隔离源码和构建产物 - 使用入口、分块和资源命名规则组织输出文件
- 配置与文件名匹配的 HTML、CDN 和浏览器缓存策略
先划清输出边界
outDir 应指向专用构建目录,不能与 src、public、项目根目录或人工维护的部署文件混用。生产构建可能清理输出目录;边界不清时,一次正常构建也可能删除不该删除的文件。
assetsDir 是相对于 outDir 的资源子目录,适合统一收纳生成的脚本、样式、字体和图片。目录名称不需要表达版本号,版本变化应交给内容哈希处理,避免每次发布都修改代码中的路径约定。
配置目录与命名规则
下面将所有产物写入 dist/web,并把入口脚本、异步分块和其他资源放入稳定的子目录。文件名保留 [name] 便于排查,加入 [hash] 便于缓存失效。
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。
执行构建:
npm run build预期输出:
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,且长期缓存资源的文件名包含内容哈希。
让目录结构服务缓存

index.html 通常不带内容哈希,因为它承担最新资源入口的职责,应使用不缓存或短缓存策略。带哈希的 JavaScript、CSS、图片和字体可设置长期缓存;内容改变后文件名随之改变,浏览器会请求新地址。
不要为了得到“固定 URL”而删除所有哈希。入口文件或外部系统确实要求稳定名称时,只对明确的文件单独处理,并确认它不会被长期缓存;否则发布新版本后,用户可能继续命中旧文件。
防止覆盖与发布残留
启用 emptyOutDir 前必须确认输出目录完全由构建系统管理。若部署流程还会把配置、证书占位或人工文件写入同一目录,应改为分目录管理,或先构建到临时目录,再由发布脚本原子替换。
发布时不要只上传新增文件。新的 index.html 可能引用新哈希资源,而旧页面仍可能引用上一版本文件;应保留短暂回滚窗口,或采用版本目录与原子切换,避免动态导入在发布瞬间请求到已删除的旧分块。
验收清单
构建后检查 dist/web 之外没有新增产物,源码目录没有被删除或修改;连续执行两次构建且源码不变时,主要资源哈希应保持稳定;修改一处业务代码后,受影响文件的哈希应变化。
最后检查部署响应头:HTML 能及时重新验证,带哈希资源可以长期缓存,静态服务器能正确返回深层路径和资源 MIME 类型。目录设计、命名规则与缓存头必须作为一套方案共同验收。