前端工程化 / 系统课时
理解项目根目录
理解项目根目录
Vite 启动失败、页面 404 或入口文件未生效,很多时候不是代码问题,而是启动位置不对。本课用一个最小项目说明当前工作目录、Vite 的 root 与 index.html 的关系,并给出可直接执行的定位方法。
学习目标
- 区分终端工作目录、Vite 项目根目录与 HTML 入口目录。
- 理解默认
root和显式指定root时,资源路径如何变化。 - 能在页面打不开时快速确认自己是否从正确目录启动。
三个位置分别负责什么
终端的当前工作目录由 pwd 显示,它决定 Vite 从哪里开始查找配置文件和依赖。未显式设置时,Vite 会把当前工作目录作为项目根目录;项目根目录中的 index.html 则是开发服务器处理页面请求时的入口。

root 不是源码目录的同义词。常见项目把源码放在 src,但仍把包含 index.html、package.json 和配置文件的上层目录作为根目录。只有明确把 root 指向其他目录时,入口位置才随之改变。
用最小项目验证默认规则
下面的命令适用于 macOS、Linux 或 Git Bash。它创建一个可运行的 Vite 项目,并从包含 index.html 的目录启动开发服务器。
mkdir vite-root-demo
cd vite-root-demo
npm init -y
npm install --save-dev vite
npm pkg set scripts.dev="vite"
mkdir src
cat > index.html <<'EOF'
<!doctype html>
<html lang="zh-CN">
<body>
<h1 id="app">正在加载</h1>
<script type="module" src="/src/main.js"></script>
</body>
</html>
EOF
cat > src/main.js <<'EOF'
document.querySelector('#app').textContent = 'Vite root 正确'
EOF
npm run dev -- --host 127.0.0.1预期输出
VITE v<VITE_VERSION> ready in <TIME> ms
➜ Local: http://127.0.0.1:<PORT>/打开输出中的地址后,页面应显示“Vite root 正确”。<VITE_VERSION>、<TIME> 与 <PORT> 会随本机环境变化。此时终端所在目录、默认 root 和 index.html 所在目录三者一致。
显式指定 root
当静态站点位于仓库子目录时,可以把该目录作为启动参数传给 Vite。假设页面文件位于 web/index.html,先停止上一条开发进程,再在仓库根目录执行命令,并把 web 作为位置参数。
mkdir web
mv index.html src web/
npm run dev -- web --host 127.0.0.1预期输出
VITE v<VITE_VERSION> ready in <TIME> ms
➜ Local: http://127.0.0.1:<PORT>/这条命令等价于把本次开发服务器的 root 指向 web。验证时应确认浏览器加载的是 web/index.html,而不是仓库根目录中的同名文件。若项目长期采用该结构,可再把 root: 'web' 固化到 Vite 配置中。
错误目录启动时如何定位
最典型的现象是开发服务器已启动,但根路径返回 404,或修改 src 后页面没有变化。先执行 pwd,再确认当前目录下是否同时存在 package.json、预期的 index.html 和实际使用的配置文件。
pwd
for file in package.json index.html web/index.html vite.config.js vite.config.ts; do
[ -f "$file" ] && printf './%s\n' "$file"
done预期输出
<PATH>/vite-root-demo
./package.json
./web/index.html若 index.html 出现在 ./web/index.html,而命令没有指定 web,就应切换目录或显式设置 root。在 IDE、任务脚本和 monorepo 中,还要检查“工作目录”设置,因为脚本名称相同并不代表启动位置相同。