前端工程化 / 系统课时

处理 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、base 与 publicDir 的路径映射

三者不能互相替代:把 root 改成 /console/ 不会实现子路径部署;把 base 指向磁盘目录也无法改变入口;把源码图片全部移入 publicDir 会失去导入分析、哈希命名和引用检查。

配置仓库子目录项目

假设仓库根目录下的 web 才是前端项目,生产环境部署到 /console/。配置文件仍放在仓库根目录,通过绝对路径消除启动目录差异。

ts
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,
  },
}))

对应目录应保持单一来源:

text
<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}

ts
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 中的资源地址:

bash
npx vite build --mode production
find dist/console -maxdepth 2 -type f | sort
grep -n "/console/assets/" dist/console/index.html

预期输出:

text
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。随后使用与生产相同的基础路径进行预览:

bash
npx vite preview --host 127.0.0.1 --port 4173

预期输出:

text
➜  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}

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

目录与阅读设置

阅读设置

17

记录一个想法

处理 root、base 与 publicDir

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

登录哪都通