跳到正文
零到全栈 · 卷 3 · 工程化与版本控制

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 托管,并做到"一条命令发布、一条命令回滚"。

→ 卷3-07-把工程发布到公网.md