前端工程化 / 系统课时
处理 root、base 与 publicDir
处理 root、base 与 publicDir
本课解决 Vite 项目中最常见的三类路径错位:入口目录找错、子路径部署后资源 404,以及公共资源被重复打包。完成后,你能为单体项目或仓库子目录配置清晰的路径边界。
学习目标
- 区分文件系统根目录、浏览器基础路径和公共资源目录
- 配置子目录项目与子路径部署
- 通过构建产物和本地预览定位资源路径错误
先分清三个坐标系
root 是文件系统坐标,决定项目入口和 index.html 所在目录;base 是 URL 坐标,决定开发与构建后的公共访问前缀;publicDir 是静态资源来源目录,其相对路径以 root 为基准。Vite 的 root 默认是当前工作目录,base 默认是 /,publicDir 默认是 <root>/public。:contentReference[oaicite:5]{index=5}

三者不能互相替代:把 root 改成 /console/ 不会实现子路径部署;把 base 指向磁盘目录也无法改变入口;把源码图片全部移入 publicDir 会失去导入分析、哈希命名和引用检查。
配置仓库子目录项目
假设仓库根目录下的 web 才是前端项目,生产环境部署到 /console/。配置文件仍放在仓库根目录,通过绝对路径消除启动目录差异。
import { resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
const repoRoot = fileURLToPath(new URL('.', import.meta.url))
export default defineConfig(({ mode }) => ({
// index.html、src 和默认 publicDir 都从 web 目录开始解析。
root: resolve(repoRoot, 'web'),
base: mode === 'production' ? '/console/' : '/',
publicDir: 'public',
build: {
outDir: resolve(repoRoot, 'dist/console'),
// outDir 位于 root 外部,显式确认允许清理该目录。
emptyOutDir: true,
},
}))对应目录应保持单一来源:
<REPO>/
├─ vite.config.ts
├─ web/
│ ├─ index.html
│ ├─ src/
│ │ ├─ main.ts
│ │ └─ logo.svg
│ └─ public/
│ └─ robots.txt
└─ dist/build.outDir 默认相对 root 解析;当输出目录位于 root 外部时,Vite 会谨慎处理清理行为,因此必须确认路径只指向专用构建目录。:contentReference[oaicite:6]{index=6}
正确引用两类资源
源码资源应通过 import 或 HTML、CSS 的可分析引用交给 Vite 处理,构建时会应用哈希和 base 前缀。需要固定文件名、无需源码导入或必须原样复制的文件才放入 publicDir。:contentReference[oaicite:7]{index=7}
import logoUrl from './logo.svg'
const logo = document.querySelector<HTMLImageElement>('#logo')
if (!logo) {
throw new Error('Missing #logo element')
}
// 导入资源会由 Vite 处理,并在生产构建中生成正确的基础路径。
logo.src = logoUrl预期结果:页面中的 #logo 元素显示构建后的图片;生产产物中的文件名带哈希,并自动使用 /console/ 前缀。
web/public/robots.txt 在源码中写作 /robots.txt,不要写成 /public/robots.txt。公共目录中的文件在开发时从根路径提供,构建时原样复制到输出目录根部。:contentReference[oaicite:8]{index=8}
当应用部署到动态子路径并需要手动拼接 URL 时,使用 import.meta.env.BASE_URL,不要把 /console/ 写死在业务代码中。该值由 base 决定,并在构建时静态替换。:contentReference[oaicite:9]{index=9}
构建并验证路径
执行生产构建,再检查输出目录和 HTML 中的资源地址:
npx vite build --mode production
find dist/console -maxdepth 2 -type f | sort
grep -n "/console/assets/" dist/console/index.html预期输出:
dist/console/assets/index-<ID>.js
dist/console/assets/logo-<ID>.svg
dist/console/index.html
dist/console/robots.txt
dist/console/index.html:<LINE>:<script type="module" crossorigin src="/console/assets/index-<ID>.js"></script>哈希、行号和文件数量会随项目变化。robots.txt 不应进入 assets,导入的 logo.svg 则应带哈希并位于 assets。随后使用与生产相同的基础路径进行预览:
npx vite preview --host 127.0.0.1 --port 4173预期输出:
➜ Local: http://127.0.0.1:4173/console/实际端口可能不同。打开页面后,同时验证 /console/、脚本文件和 /console/robots.txt;若首页正常但刷新子路由 404,还需要在部署服务器配置 SPA 回退,这不是修改 root 或 publicDir 能解决的问题。
按现象定位错位
出现“找不到 index.html”时,先检查启动目录与 root;出现构建成功但静态资源 404 时,检查部署实际前缀是否与 base 一致;出现同名资源重复时,确认文件是否同时存在于 src 和 publicDir。如果应用必须嵌入任意目录,可将 base 设为 ./ 或空字符串,使生成 URL 使用相对路径,但要先验证路由与宿主页面约束。:contentReference[oaicite:10]{index=10}