[!info] 关联笔记

• 所属 MOC：Vite 基础 MOC
• 前置：Vite 的设计动机
• 后续：依赖预构建 · 生产构建 · HMR

Vite 开发与构建双路径

这个概念为什么出现

只记命令 vite / vite build 而不理解管线，会出现：

• dev 下动态 import 正常，build 后路径或拆包不符合预期
• 依赖在 dev 被预构建“修好”，prod 却以另一套解析出现
• 把 dev-only 假设（宽松、快速）带进生产排障

[!abstract] 一句话理解 开发路径优先“快反馈”，生产路径优先“可部署产物”；它们共享插件与配置语义，但不共享同一条执行管线。

最小可运行示例

场景：运营配置台要在本地秒开，同时 CI 产出可缓存静态资源

// vite.config.ts
// 业务意图：同一份配置同时服务 dev 与 build，但不假装两条管线相同。
// 教学点：plugins/resolve 共享；server 只影响开发，build 只影响产物。
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { '@': path.resolve(__dirname, 'src') },
  },
  server: {
    port: 5173,
    // 仅 dev：把 /api 代理到本地后端，避免浏览器跨域
    proxy: { '/api': 'http://localhost:3000' },
  },
  build: {
    // 仅 prod：产物目录与 sourcemap 策略
    outDir: 'dist',
    sourcemap: true,
  },
})

建议运行：

pnpm dev
# 另开终端
pnpm build && pnpm preview

期望观察：

dev：浏览器 Network 出现大量 /src/* 模块请求；
build：dist 下出现打包后的 assets/*.js 与 hash 文件名；
preview：以生产产物被静态服务，不再按源码路径请求。

结合场景再看三个关注点

1. server.* 不进入生产包逻辑。
2. build.* 不解释你为何本地代理成功。
3. 共享的是模块语义与插件，不是“同一种打包中间态”。

核心模型

flowchart LR
  SRC[源码] --> DEV[Dev Server 按需转换]
  DEP[node_modules] --> PRE[esbuild 预构建缓存]
  PRE --> DEV
  DEV --> BR[浏览器 ESM 运行]
  SRC --> ROLL[Rollup 生产构建]
  DEP --> ROLL
  ROLL --> DIST[dist 静态产物]

边界情况

• 某些 Node 内置模块在浏览器 dev 可能靠 polyfill 插件“看起来能用”，prod 仍需明确 external/polyfill 策略。
• import.meta.env 在 build 时静态替换；运行时读不到未声明变量的“动态环境文件”。

常见误区

[!warning] 常见误区：preview 约等于 dev preview 服务的是 build 产物，用来验证生产路径，不是第二套 dev server。

工程实践

• PR 检查至少包含 build，不要只靠 dev 截图。
• 出现 dev/prod 不一致时，列出：别名、环境变量、依赖预构建、SSR 条件分支。

本节总结

双路径是 Vite 的骨架。先分清“谁在服务模块、谁在产出文件”，再谈优化才有坐标系。

自测题

1. 为什么 proxy 配在 server 而不是 build？
2. 如何快速确认当前页面跑在 dev 还是 preview？

参考答案

1. proxy 是开发服务器网络能力，生产应由网关/Nginx/同源 API 处理。
2. 看 Network 是源码模块路径还是 /assets/index-*.js 一类打包资源。

延伸阅读

资料	类型	支撑内容
Why Vite	官方	动机与对比
Building for Production	官方	生产构建