Skip to content

约 3 分钟阅读

Vite:开发反馈、生产构建与路径合同 ​

Vite 提供开发服务器和生产构建。开发阶段按浏览器请求转换源码并维护模块更新关系;生产阶段从入口构建依赖图,输出可部署资源。开发启动、依赖扫描和 HMR 都受模块数量、插件、文件系统与更新边界影响,不能承诺“项目再大耗时也恒定”。

本页按 Vite 8 解释:依赖优化与生产打包使用 Rolldown,JavaScript 转换和默认压缩使用 Oxc。旧版本的 Rollup/esbuild 配置不能原样当作当前机制;迁移时要连同框架插件、目标浏览器、配置项和锁文件一起核对。

Vite 的开发模块路径与生产发布路径

一个可部署到子路径的项目 ​

下面创建独立演示项目,选择符合 Vite 8 要求的 Node 版本,例如 Node 22.12+。锁文件与 Node、npm 版本一起保存,后续在干净环境使用 npm ci。

bash
mkdir vite-demo
cd vite-demo
npm init -y
npm pkg set type=module
npm install -D vite@^8 typescript
npm pkg set 'scripts.dev=vite' 'scripts.build=tsc --noEmit && vite build' 'scripts.preview=vite preview'
mkdir src

根目录的 index.html 是入口,资源通过依赖图进入构建:

html
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>数量演示</title>
<button type="button">加一件</button>
<output aria-live="polite">1</output>
<script type="module" src="/src/main.ts"></script>
</html>

src/main.ts 只处理本地数量,样式放在 src/style.css,例如 body { font-family: sans-serif; }。

ts
import './style.css';

const button = document.querySelector<HTMLButtonElement>('button');
const output = document.querySelector<HTMLOutputElement>('output');
if (!button || !output) throw new Error('入口控件缺失');
let quantity = 1;
button.addEventListener('click', () => {
  output.value = String(++quantity);
});

tsconfig.json 确定检查范围。Vite 能转换 TypeScript 不等于完成类型检查,所以构建脚本单独运行 tsc。

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022", "DOM"],
    "strict": true,
    "noEmit": true
  },
  "include": ["src"]
}

vite.config.mjs 声明部署前缀。这里保留默认打包策略,需要定制底层选项时再使用 Vite 8 的 build.rolldownOptions,避免先堆分包配置。

js
import { defineConfig } from 'vite';

export default defineConfig({
  base: '/shop/',
  server: { host: '127.0.0.1', port: 5187, strictPort: true },
  build: { outDir: 'dist', sourcemap: false },
});

先 npm run dev 点击按钮,再 npm run build、npm run preview 访问输出中的 /shop/。检查 HTML 引用的 JS/CSS 都带正确前缀,刷新后控件仍能工作。预览只服务构建产物,不能代替正式服务器的重写、缓存和权限配置。

插件、HMR 与依赖优化 ​

Vue SFC、React Fast Refresh 等需要对应插件。插件里的转换工作、依赖解析和生成产物职责不同,不是每个 Rollup 插件都能不加判断用于开发服务器。添加插件先确认当前 Vite 大版本、插件 peerDependencies、执行环境以及使用的 hook。

HMR 会沿受影响模块图寻找可接受更新的边界;找到时局部更新,找不到或插件要求时可整页刷新。组件状态是否保留取决于更新类型与框架集成,普通模块的局部变量不应被当作持久状态。自行接入定时器或监听器时,要在 dispose 中撤销旧资源。

依赖预构建主要改善开发时的依赖访问;生产构建是另一条路径。遇到链接包或新增依赖识别异常,可以在保存现场后运行 npm run dev -- --force 重建优化缓存。缓存清理不是所有解析错误的通用修复,仍需检查依赖声明、导出条件和路径大小写。

环境与资源的边界 ​

VITE_ 前缀变量会暴露给浏览器代码,.env.local 只影响本地版本管理约定,不会让进入构建的值变成秘密。密钥放在后端;客户端只使用可公开配置,例如 API 路径或站点名称。import.meta.env 中自定义值默认是字符串,"false" 不能直接当布尔值。

--mode staging 选择 mode 相关配置,不等价于切换生产优化或任意 Node 环境变量。开发代理仅对开发服务器有效,生产 API 路由要由网关或后端部署实现;增加 cors: true 也不能让别的服务器自动允许跨源。

源码 import 的资源可进入指纹化与转换;默认 public/ 的文件原样复制,不能一律套用 immutable 长缓存。项目也可能自定义 publicDir,应看实际配置。base 不会自动重写任意运行时拼出的字符串 URL,动态路径应按部署合同生成。

排查与验收 ​

现象先取什么证据修正方向
开发正常,子路径资源404生产HTML与Network实际URLbase、资源引用和服务器挂载前缀一致
构建过了,类型仍错误tsc或框架类型检查输出将独立类型检查纳入门禁
更新后整页刷新HMR日志、变动模块与插件判断是否有接受边界,不承诺保留任意状态
浏览器里出现内部值构建文件、env前缀与define从客户端产物移除秘密,必要时轮换已泄露凭据
首次导入慢依赖优化日志、请求瀑布先区分下载、转换和模块数量,再调整

升级前对照 开发与构建模型,发布继续看 交付与可观测性。不要用增大 chunk 警告阈值冒充包体积优化,也不要为了减小包而外部化浏览器无法解析的依赖。

别急,先让缓存热一下。