Vite:开发与构建
本合集目录
本章目录
单册说明:本文件是卷 3 的第 6 章,可独立阅读。前置:第 4 章(ESM)、第 5 章(npm)。本章把「读到」迁到 Vite:开发时秒开热更新,发布时产出一份能整包上传的
dist/。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 3 · 工程化与版本控制(第 6 / 7 章) |
| 前置章节 | 3.5 npm 与依赖管理 |
| 本章产出 | src/ 目录 · vite.config.js · 两份环境变量文件 · 一个 dist/ 产物 |
| 对应代码 | dudao/vite.config.js、dudao/src/*、dudao/.env.example |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能说出 dev 与 preview 的区别,并解释为什么 dist/index.html 双击打不开 |
3.6.1 一句话结论:开发不打包,发布才打包
Vite 的核心决定只有一句:开发时把源码当原生 ESM 直接喂给浏览器,一个文件都不合并;发布时才用打包器压成少数几个文件。 前半句解决了"改一行要等十秒",后半句解决了"几百个请求拖慢首屏"。
真实失败场景:npm run build 成功,dist/ 也生成了,你把整个文件夹传到服务器,打开域名一片空白,Console 里写着:
Failed to load module script: Expected a JavaScript-or-Wasm module script
but the server responded with a MIME type of "text/html". Strict MIME type
checking is enforced for module scripts per HTML spec.
这不是构建失败,是路径错了:浏览器去请求 /assets/index-xxxx.js,服务器找不到,按 SPA 规则回退返回了 index.html,于是 JS 的响应内容是 HTML。第 7 章会从这个报错讲起。
3.6.2 原理:三态、产物与环境变量
① 为什么开发能快
传统打包器的工作方式是:启动 → 把你的全部源码和依赖读一遍 → 打包 → 起服务。项目越大,启动越慢,改一个文件还要重新打包相关模块。
Vite 换了个思路:
| 阶段 | 做法 | 代价 |
|---|---|---|
| 启动 | 只启动一个 HTTP 服务,不碰你的源码 | 几乎为零 |
浏览器请求 main.js |
现场把这个文件转成浏览器能懂的 JS,返回 | 单文件毫秒级 |
遇到 import './render.js' |
浏览器自己再发一个请求,Vite 再转那一个 | 按需,不用的文件永远不转 |
遇到 import 'some-lib' |
从预构建缓存里取(依赖已用 esbuild 提前打成整块) | 一次性,之后走缓存 |
两个关键设计:按需转换(只处理浏览器真的要的文件)和依赖预构建(把 node_modules 里几百个小模块合并成几十个,避免请求瀑布)。这就是"冷启动一秒内"的来源。
但开发模式不能直接上线,原因很实在:
| 问题 | 开发模式 | 生产需要 |
|---|---|---|
| 请求数 | 一个模块一个请求,大项目上百个 | 越少越好 |
| 体积 | 不压缩、带 sourcemap、含 HMR 代码 | 压缩、去调试代码 |
| 兼容 | 假设浏览器支持 ESM | 可能要兼容旧浏览器 |
| 缓存 | 文件名不带哈希 | 文件名带内容哈希,才能长期缓存 |
所以 build 仍然用打包器(Vite 用 Rollup)做一次完整优化。开发和发布用两套策略,是 Vite 最重要的取舍。
② dev / build / preview 三态
| 命令 | 干什么 | 默认地址 | 能不能给别人用 |
|---|---|---|---|
npm run dev |
起开发服务器,按需编译 + 热更新 | http://localhost:5173 |
不能。未压缩、依赖 HMR、性能差 |
npm run build |
打包到 dist/,压缩、加哈希、抽 CSS |
不起服务 | — |
npm run preview |
用静态服务器托管 dist/,本地验收 |
http://localhost:4173 |
临时可以,但它不是生产服务器 |
preview 常被误解为"上线"。它只是把构建产物按生产的方式跑一遍,让你在发布前发现路径、环境变量、资源引用的问题。它没有缓存策略、没有 gzip 配置、没有并发能力——那些是 Nginx 的事。
③ dist/ 里到底有什么
npm run build
形如:
vite v7.1.2 building for production...
✓ 12 modules transformed.
dist/index.html 0.62 kB │ gzip: 0.38 kB
dist/assets/index-DiwrgTda.css 3.41 kB │ gzip: 1.22 kB
dist/assets/index-C8kQ2m1p.js 14.87 kB │ gzip: 5.03 kB
✓ built in 412 ms
| 文件 | 说明 |
|---|---|
index.html |
入口,里面的 <script src> 已被改写成带哈希的产物路径 |
assets/index-<哈希>.js |
所有 JS 打成一个文件(本项目小,只有一个 chunk) |
assets/index-<哈希>.css |
从 JS 里 import 的 CSS 被抽出来单独成文件 |
public/ 里的东西 |
原样拷贝到 dist/ 根,不加哈希 |
那个八位哈希是内容哈希:内容变,哈希变,文件名就变。于是可以给这些文件设一年的强缓存——文件名一变,浏览器自然去拿新的。index.html 相反,绝不能缓存,否则用户永远看不到新版本。第 7 章会把这两条规则写进 Nginx。
④ 环境变量:只有一个前缀能过墙
Vite 里的环境变量分两类:能进客户端的和只给配置用的。分界线是前缀 VITE_。
// 能被替换成字面量,因为以 VITE_ 开头
const siteName = import.meta.env.VITE_SITE_NAME;
// 没有前缀,构建时就是 undefined
const secret = import.meta.env.DB_PASSWORD;
为什么这么设计?因为前端代码是公开的。任何打进 dist/ 的字符串,用户按 F12 就能看到。VITE_ 前缀是一道物理隔离:没这个前缀,构建工具根本不会把它注入客户端代码,你想泄露都泄露不了。
| 变量 | 含义 | 谁可以用 |
|---|---|---|
import.meta.env.MODE |
当前模式,development 或 production |
客户端 |
import.meta.env.DEV / PROD |
布尔值,判断当前是不是开发 | 客户端 |
import.meta.env.BASE_URL |
配置里的 base 值 |
客户端 |
import.meta.env.VITE_* |
你自定义的、允许公开的变量 | 客户端 |
| 无前缀变量 | 只在 vite.config.js 里通过 loadEnv 读取 |
仅构建期 |
文件的加载有优先级,后面的覆盖前面的:
| 文件 | 何时加载 | 进不进仓库 |
|---|---|---|
.env |
所有模式 | 可进,但本项目忽略(更稳妥) |
.env.local |
所有模式 | 不进(放本机差异) |
.env.production |
仅 build |
进 |
.env.production.local |
仅 build |
不进 |
本项目只用其中的 .env.local,其余几行是你在别的项目里会遇到的写法,认得即可。
规则记一条就够:带 .local 的都不进仓库;进客户端的都必须带 VITE_;真正的密钥(数据库密码、API Secret)永远不要放在前端项目的任何 .env 里——它们属于卷 5 的后端。
⑤ public/ 与 src/assets/ 的分工
| 放哪 | 怎么引用 | 会不会被处理 | 适合什么 |
|---|---|---|---|
public/ |
/favicon.svg(绝对路径,原样写) |
不处理、不改名、不加哈希 | favicon.ico、robots.txt、需要固定路径的文件 |
src/assets/ |
import logo from './assets/logo.svg' |
会处理:小图转 base64、大图加哈希 | 组件里用到的图片、字体 |
一个常见错误:把图片放 public/,然后在 JS 里 import '/logo.png'。public 里的东西不该被 import——它不经过构建,import 拿不到导出的 URL。反过来,把需要在固定路径访问的文件(比如 robots.txt)放 src/assets 也不行,它会被改名。
⑥ base:部署在根目录还是子目录
base 决定产物里的资源路径前缀。
| 部署位置 | 访问地址 | base 写什么 |
dist/index.html 里的路径 |
|---|---|---|---|
| 域名根 | https://dudao.example.com/ |
'/'(默认) |
/assets/index-xxx.js |
| 子目录 | https://example.com/dudao/ |
'/dudao/' |
/dudao/assets/index-xxx.js |
| 任意位置(相对) | 不固定 | './' |
./assets/index-xxx.js |
'./' 看起来最省事,但它只适合"页面永远在同一个目录层级"的项目。一旦你以后加了前端路由(/note/123 这种路径),相对路径会从当前 URL 推,直接失效。本项目现在没有路由,但卷 4 会有,所以默认用 '/',要放子目录就明确写 '/dudao/'。
3.6.3 动手:把「读到」迁到 Vite
第 1 步:整理目录
目标结构:
dudao/
├─ index.html ← 必须在项目根
├─ package.json
├─ vite.config.js
├─ .env.example
├─ public/
│ └─ favicon.svg
└─ src/
├─ main.js
├─ store.js
├─ render.js
├─ events.js
└─ styles.css
执行:
mkdir src public
git mv js/main.js js/store.js js/render.js js/events.js src/
git mv styles.css src/styles.css
git mv 等于"移动 + 记录为重命名",历史不会断。此时 index.html 里的引用全断了,下一步修。
再放一个图标占位文件 public/favicon.svg,后面 index.html 会引用它:
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
<rect width="32" height="32" rx="6" fill="#1f2937"/>
<text x="16" y="22" font-size="16" text-anchor="middle" fill="#ffffff">读</text>
</svg>
public/ 里的文件会原样出现在 dist/ 根目录,路径固定、不加哈希——这就是它和 src/assets/ 的区别。
如果你是从零新建项目,官方脚手架是
npm create vite@latest dudao -- --template vanilla,它会生成一套带计数器示例的骨架。本卷刻意手工迁移:你需要在每一步知道哪个文件被移动了、哪条引用断了。脚手架能省五分钟,但省不掉理解。
第 2 步:index.html 只留一个入口
Vite 要求 index.html 在项目根目录,并且样式不再用 <link> 引入(改由 JS import,这样构建时才能抽取和压缩)。改成:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="icon" href="/favicon.svg" type="image/svg+xml">
<title>读到 · 我的摘录</title>
</head>
<body>
<header class="site-header">
<h1>读到</h1>
<p class="tagline">把读到的句子留住</p>
</header>
<main>
<form id="note-form" class="note-form">
<input id="title" name="title" type="text" placeholder="标题" required>
<textarea id="content" name="content" placeholder="摘录正文" required></textarea>
<input id="source-url" name="sourceUrl" type="url" placeholder="来源链接(可选)">
<input id="tags" name="tags" type="text" placeholder="标签,用逗号分隔">
<button type="submit">存下</button>
</form>
<section class="toolbar">
<div id="tag-bar" class="tag-bar"></div>
<p id="stats" class="stats"></p>
</section>
<ul id="note-list" class="note-list"></ul>
</main>
<script type="module" src="/src/main.js"></script>
</body>
</html>
注意 src="/src/main.js" 是开发时的真实路径,不是产物路径。构建时 Vite 会把它改写成 /assets/index-<哈希>.js。
第 3 步:让 main.js 引入样式
在 src/main.js 顶部加一行:
import './styles.css';
这一行就是第 4 章说的"副作用导入":不需要任何导出,只为让构建器知道"这个 CSS 属于这个入口"。构建后它会变成一个独立的 .css 文件,并在 index.html 里自动插入 <link>。
第 4 步:写 vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
base: '/',
server: {
port: 5173,
open: false,
},
build: {
outDir: 'dist',
assetsDir: 'assets',
sourcemap: false,
},
});
四个字段的含义:base 是资源前缀;server.port 固定端口,免得每次换;build.outDir 产物目录;sourcemap: false 表示不生成映射文件(生产环境暴露源码结构,需要排查线上问题时再临时开)。
第 5 步:环境变量
.env.example(提交,作用是一份"需要配哪些变量"的说明):
# 站点名,会显示在页面标题上
VITE_SITE_NAME=读到
.env.local(不提交,本机真正生效的那份):
VITE_SITE_NAME=读到(本地)
这里刻意不用 .env:上一章的 .gitignore 已经把 .env 整类挡住了,那是更安全的默认值。团队约定是"照 .env.example 复制一份 .env.local"——需要配置什么写在提交的文件里,具体填什么写在不提交的文件里。
在 main.js 里用起来:
const siteName = import.meta.env.VITE_SITE_NAME ?? '读到';
document.title = `${siteName} · 我的摘录`;
document.querySelector('.site-header h1').textContent = siteName;
确认 .gitignore 里有 .env.local。.env 与 .env.local 都不进仓库,进去的只有 .env.example 这份"键名清单"——这条边界现在就要立好,卷 5 会感谢你。
第 6 步:开发模式跑一遍
npm run dev
形如:
VITE v7.1.2 ready in 287 ms
➜ Local: http://localhost:5173/
打开后做三件事验证热更新:改 styles.css 里 .tag 的颜色 → 不刷新页面,颜色立刻变;改 render.js 里空状态的文案 → 列表立刻更新;看 Console,应该没有报错。
热更新的价值不在"快",在"不丢状态"。 用 python -m http.server 时,改一行要手动刷新,表单里填了一半的内容全没了;HMR 只替换改动的那部分,状态还在。
第 7 步:构建,并检查产物
npm run build
ls dist dist/assets
形如:
dist/index.html
dist/favicon.svg
dist/assets/index-C8kQ2m1p.js
dist/assets/index-DiwrgTda.css
看一眼 dist/index.html:
cat dist/index.html
形如:
<script type="module" crossorigin src="/assets/index-C8kQ2m1p.js"></script>
<link rel="stylesheet" crossorigin href="/assets/index-DiwrgTda.css">
三件事被改写了:路径变成 /assets/...、文件名带哈希、加了 crossorigin。这就是为什么 dist/index.html 双击打不开——file:// 下 /assets/... 指向的是磁盘根目录,而且模块脚本依然受 CORS 限制。
第 8 步:用 preview 验收
npm run preview
形如:
➜ Local: http://localhost:4173/
在这个地址上把功能全过一遍:新增、筛选、刷新后数据还在、Console 无红字。preview 通过,才说明构建产物是好的,可以进入发布环节。
最后提交(dist/ 不进仓库):
git add -A
git commit -m "build: 迁移到 Vite,产出 dist"
3.6.4 三个坑
坑 1:环境变量没加 VITE_ 前缀
症状:页面上显示 undefined,或者标题变成 undefined · 我的摘录。代码没报错,因为 undefined ?? '读到' 只在变量真的是 undefined 时生效——你写了 import.meta.env.SITE_NAME,它确实是 undefined,但如果再往下取属性就会崩:
Uncaught TypeError: Cannot read properties of undefined (reading 'length')
成因:前缀缺失。构建时 Vite 只把 VITE_ 开头的键注入 import.meta.env,其余键在客户端代码里被静态替换成 undefined(甚至整个对象被裁掉)。
修法:改名成 VITE_SITE_NAME,然后重启 dev server。环境变量在启动时读取,改 .env 不重启不会生效——这一点和热更新无关,HMR 不会重载环境变量。
坑 2:public/ 里的文件被 import,或路径写错
症状:图片 404,或构建时报:
[plugin:vite:import-analysis] Failed to resolve import "/logo.png" from "src/main.js".
Does the file exist?
成因:public/ 下的文件不参与模块解析,import '/logo.png' 既不是相对路径也不是合法包名;或者文件放在 src/assets/ 却按 /logo.png 引用,开发时能碰巧命中(Vite 把根目录也当静态根),构建后就 404。
修法:按用途分——固定路径的文件放 public/,用 /favicon.svg 这种绝对路径直接写在 HTML 或 CSS 里,不要 import;需要被构建处理的资源放 src/assets/,用 import logoUrl from './assets/logo.svg' 拿到最终 URL,再赋给 img.src。CSS 里的 url() 用相对路径,Vite 会自动改写。
坑 3:base 配错,上线后资源全变 HTML
症状:本地 preview 正常,部署到子目录后白屏,Console 报本章开头那段 MIME 错误,Network 里 JS 请求返回 200 但 Content-Type: text/html。
成因:base 还是 '/',浏览器去请求 /assets/index-xxx.js,而文件实际在 /dudao/assets/...。服务器找不到路径,SPA 的 try_files 回退把 index.html 返回了,于是"JS 的内容是 HTML"。
修法:把 base 改成部署的实际前缀('/dudao/'),重新 build。改完一定要看 dist/index.html 里的路径,这是最快的验证方式,比部署上去再猜快十倍。
本章验收
- 目录里
index.html在根、源码在src/、图片资源按public/assets分工放好 -
npm run dev起在 5173,改 CSS 与 JS 都能热更新且不丢表单内容 -
npm run build产出dist/,dist/index.html里引用的是带哈希的/assets/... -
npm run preview下所有功能正常,Console 无红字 -
.env.local被.gitignore挡住,.env.example已提交 - 能解释
dev与preview的区别,以及为什么dist/index.html不能双击打开
自测
Q1:为什么 Vite 开发时不打包,生产却一定要打包?
看答案
开发时按需转换、浏览器原生 ESM 加载,启动和更新都只处理被请求的文件,所以快;但代价是请求数多、代码未压缩、带 HMR 代码。生产环境要减少请求、压缩体积、做 tree-shaking、给文件名加内容哈希以便长期缓存,这些都必须整体分析依赖图,所以要用 Rollup 打一次包。两套策略针对两个不同目标,不是重复劳动。Q2:import.meta.env.VITE_API_URL 和 import.meta.env.API_URL 有什么区别?如果 API 地址里带密钥呢?
看答案
前者会被构建时替换成真实值并打进产物,后者是 `undefined`。区别来自 `VITE_` 前缀这道过滤。但即便有前缀,也不该把带密钥的完整地址放前端——产物是公开的,任何人打开 DevTools 都能读到。密钥应该留在后端,前端只拿一个公开的接口地址。Q3:npm run preview 能访问,把 dist/ 原样拷到服务器却 404,最可能是什么问题?
看答案
路径前缀。`preview` 把 `dist/` 当作站点根,所以 `base: '/'` 下的 `/assets/...` 能找到;服务器上如果部署在子目录,文件实际在 `/dudao/assets/...`,根路径就 404。其次是 Nginx 的 `root` 指错层级(指到了 `dist` 的父目录)。两者都能通过看 `dist/index.html` 里的路径和 `curl -I` 具体资源 URL 快速区分。下一步
dist/ 有了,preview 也过了。最后一章把它搬到服务器上,用 Nginx 托管,并做到"一条命令发布、一条命令回滚"。