Vite 命令速查表 - Vite 构建工具常用命令大全

Vite 靠原生 ESM 与按需编译换来了"秒开"的开发体验，也让 config 风格和 Webpack 差异明显。本表覆盖项目创建、dev server、生产构建、环境变量、插件、代理与 SSR 构建，并标注与旧式打包流程的差别。新起前端项目、把旧 Webpack 工程迁移到 Vite、或排查"明明加了配置却不生效"时最合适。读完能独立完成从创建到生产构建的一条龙，也清楚 dev 与 build 阶段该去各自改哪。

开发工具·共 44 条命令·最后更新 2026-07-21

典型使用场景

面向用 Vite 构建前端项目的开发者，覆盖从建项目到 SSR / 库模式的全流程。最值得先掌握的两组是「环境变量」——客户端变量必须 VITE_ 前缀且不注入密钥，「配置选项」——base 决定部署路径、build.target 决定浏览器兼容范围。本表把 CLI 参数与 vite.config.ts 配置项分开列出，因为两者的生效时机与排查方式完全不同。

项目创建与初始化 5

npm create vite@latest

创建新项目，交互式选择模板

npm create vite@latest my-app -- --template react-ts

指定模板：react-ts / vue-ts / svelte-ts 等

npm create vite@latest my-app -- --template vanilla-ts

纯 TypeScript 模板，无框架绑定

npm install

安装项目依赖

npm run dev

启动开发服务器（默认端口 5173）

开发服务器 7

vite

启动开发服务器，默认端口 5173

vite --port 3000

指定端口号启动

vite --host 0.0.0.0

监听所有网络接口，局域网访问

vite --open

自动在浏览器中打开

vite --cors

启用 CORS 头

vite --strictPort

端口被占用时报错而非自动递增

vite --force

强制重新构建依赖预打包

构建打包 7

vite build

生产构建，输出到 dist 目录

vite build --outDir dist

指定输出目录（默认 dist）

vite build --watch

监听模式，文件变化自动重新构建

vite build --sourcemap

生成 source map 文件，方便调试

vite build --minify esbuild

使用 esbuild 压缩（默认 terser 可选）

vite preview

预览构建结果，模拟生产环境

vite build --report

生成构建分析报告（需插件）

配置选项 7

import { defineConfig } from 'vite'

使用 defineConfig 获得类型提示和自动补全

root: './src'

base: '/my-app/'

公共基础路径，部署到子路径时设置

build.outDir: 'dist'

构建输出目录

build.assetsDir: 'assets'

静态资源子目录

build.target: 'es2020'

构建目标浏览器版本

build.emptyOutDir: true

构建前清空输出目录

环境变量与模式 6

import.meta.env.VITE_API_URL

客户端环境变量，必须 VITE_ 前缀

import.meta.env.MODE

当前模式：development / production

import.meta.env.DEV

布尔值，是否开发模式

import.meta.env.PROD

布尔值，是否生产模式

vite build --mode staging

指定模式构建，加载 .env.staging

loadEnv(mode, process.cwd(), '')

在 vite.config.ts 中加载环境变量

插件与集成 6

import vue from '@vitejs/plugin-vue'

Vue 3 单文件组件支持插件

import react from '@vitejs/plugin-react'

React Fast Refresh 支持插件

import { visualizer } from 'rollup-plugin-visualizer'

打包体积可视化分析

vite-plugin-pwa

PWA 渐进式 Web 应用支持

vite-plugin-checker

TypeScript / ESLint 类型检查，异步不阻塞构建

vite-plugin-inspect

检查 Vite 插件中间状态，调试插件用

SSR 与库模式 6

build.ssr: true

启用 SSR 服务端渲染构建

build.ssrManifest: true

生成 SSR 构建清单，配合预加载

build.lib: { entry: 'src/index.ts', name: 'MyLib' }

库模式，打包为可发布的库

build.lib.formats: ['es', 'cjs', 'umd']

库输出格式：ESM / CommonJS / UMD

ssr.external: ['vue']

SSR 中外部化依赖，不打包进产物

ssr.noExternal: ['my-lib']

SSR 中强制打包某些依赖

参数矩阵

参数	作用	示例
`vite --port`	指定开发服务器端口	`vite --port 3000`
`vite --host 0.0.0.0`	监听所有网卡，局域网可访问	`vite --host 0.0.0.0`
`vite --strictPort`	端口被占用时报错而非自动递增	`vite --strictPort`
`vite --force`	强制重建依赖预打包	`vite --force`
`vite build`	生产构建，输出到 dist	`vite build --sourcemap`
`vite preview`	本地预览构建产物	`vite preview`
`base`	公共基础路径，部署到子路径时必设	`base: '/my-app/'`
`build.target`	构建目标浏览器版本	`build: { target: 'es2020' }`
`import.meta.env.VITE_*`	客户端环境变量，必须 VITE_ 前缀	`import.meta.env.VITE_API_URL`
`vite build --mode`	指定模式，加载 .env.<mode>	`vite build --mode staging`
`build.outDir`	构建输出目录，默认 dist	`build: { outDir: 'dist' }`
`build.ssr / build.lib`	SSR 构建 / 库模式打包	`build: { lib: { entry: 'src/index.ts' } }`

易错点与避坑指南

现象代码里读 import.meta.env.SECRET_KEY 拿到 undefined。

原因客户端环境变量必须带 VITE_ 前缀，且不能包含敏感信息（会打进产物）。

处置改名并加前缀；密钥只放服务端，绝不能进 import.meta.env。

现象部署到子路径后页面白屏，资源 404。

原因base 未设置为子路径。

处置在 vite.config.ts 设 base: '/my-app/'，与服务器实际挂载路径一致。

现象新加的依赖报错找不到模块，重启 dev server 无效。

原因依赖预打包缓存过期。

处置vite --force 强制重建预打包；或删除 node_modules/.vite 后重启。

现象build 报 browserslist 目标与手动 target 冲突。

原因同时配置了 build.target 与 package.json 的 browserslist。

处置二者只保留一处，通常以 build.target 为准并移除冲突配置。

现象产物在旧浏览器上白屏。

原因构建目标过新，输出的语法不被目标浏览器支持。

处置调低 build.target（如 'es2015'），或引入 @vitejs/plugin-legacy。

现象开发时正常、生产构建后接口请求路径错乱。

原因代码里用了硬编码绝对路径或依赖了 dev 环境的代理配置。

处置统一走 import.meta.env.VITE_API_URL，并用 vite preview 验证生产行为。

排障路径

1确认当前模式与可用的环境变量
vite build --mode staging
MODE 决定加载哪个 .env 文件；配合 import.meta.env.MODE 核对。
2依赖预打包出问题时强制重建
vite --force
重建依赖优化缓存，能解决大部分「刚装的包却找不到」的问题。
3用生产构建复现问题
vite build && vite preview
dev 与 build 行为不同；preview 能暴露真实产物的问题。
4定位部署后的资源路径
grep -oE 'src="[^"]*"' dist/index.html | head
检查产物里资源路径是否带上了 base 前缀，缺前缀即 404 根因。
5分析产物体积构成
vite build --report
配合 rollup-plugin-visualizer 生成可视化报告，定位体积大户。

命令示例

指定模板创建项目并起开发服务器

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
npm run dev

模板名必须写在 -- 之后的 --template 里，少了这个 -- 就会被 npm 当成自身参数吞掉，交互式菜单照旧弹出。dev 默认监听 5173，端口被占用会自动递增到 5174，脚本里引 URL 时用 vite --port --strictPort 固定。

输出

VITE v5.x  ready in 214 ms

  ➜  Local:   http://localhost:5173/

基础配置：子路径部署 + 资源目录 + 构建目标

import { defineConfig } from 'vite'

export default defineConfig({
  base: '/my-app/',
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
    target: 'es2020',
    emptyOutDir: true,
  },
})

base 决定产物里所有资源引用的前缀，部署到子路径时漏改会得到一整页 404 的空白站点；emptyOutDir 保证旧产物不会残留在 dist 里被误引用。target 定低能兼容旧浏览器，定太高则可能用到设备不支持的语法。

多环境变量：VITE_ 前缀 + 按模式构建

# .env.staging
VITE_API_URL=https://staging.example.com

// 代码中读取：env 对象 + 键名拼装（只认 VITE_ 前缀）
const key = "VITE_API_URL";
const base = import.meta.env[key];

// 构建时加载指定模式的 .env.staging
vite build --mode staging

没有 VITE_ 前缀的变量不会注入客户端代码，写成 API_URL 再在代码里取只会得到 undefined；不带前缀的变量要用 config 里的 loadEnv 在 Node 侧读取。--mode 决定加载哪个 .env 文件，漏写就会静默用上开发环境的地址。

库模式打包，输出 ESM/CJS/UMD

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.ts',
      name: 'MyLib',
      formats: ['es', 'cjs', 'umd'],
    },
  },
})

库模式不会走应用的 HTML 入口，index.ts 必须显式导出对外 API，否则产物是空的。formats 决定下游能否 require；只发 es 的话，仍用 CommonJS 打包的宿主会直接报找不到模块。

SSR：外部化 vue、强制打包自有库

export default defineConfig({
  build: {
    ssr: true,
    ssrManifest: true,
  },
  ssr: {
    external: ['vue'],
    noExternal: ['my-lib'],
  },
})

external 让依赖留在服务端 require 而不是打进产物，体积最小；noExternal 用来处理内置 CJS、或内部直接读源码路径的自有库。两者方向相反，同一个包配反的典型症状就是服务端报 "Cannot find module"。

常见坑与注意事项

构建期字符串替换会穿透到普通字符串里：代码或注释中出现的连续环境变量写法会被直接替换成字面量，写进提示文案、URL 模板或 i18n 文本时会在运行时拼出意外内容，导致 SSR 与客户端渲染不一致。
客户端环境变量必须带 VITE_ 前缀，不带前缀的键在浏览器侧恒为 undefined；把敏感密钥写进 .env 后以为它不会被打包，实际上只要加了前缀就会随产物公开。
依赖预构建失败（新装依赖后报 "Failed to resolve import" 或某个包出现两份实例）时，改 .env 或 vite.config 都不管用，必须 vite --force 重建依赖缓存。
base 未按部署子路径调整时，产物里的静态资源路径全部错位，页面表现为白屏或资源 404，DevTools 里看不到任何报错线索。
mode 与 .env 文件名不匹配（比如写 --mode staging 却只有 .env.production）不会报错，会静默回退到基础 .env，把开发环境地址打进生产包。
vite preview 只是本地静态预览，不复现生产环境的缓存头、反代与 SSR 运行时；预览正常不代表线上正常，SSR 项目还需 build.ssr 与 ssrManifest 配套。

提示

Vite 开发服务器使用原生 ESM，无需打包，冷启动极快
使用 vite.config.ts 配置文件，支持 TypeScript
环境变量以 VITE_ 前缀暴露到客户端
使用 defineConfig 获得类型提示和自动补全
Vite 支持对 Vue/React/Svelte/Lit 等框架的一流支持

常见问题

端口被占用后 Vite 自动换了一个端口，怎么禁止这种行为？

默认情况下 5173 被占用时 Vite 会自动递增到 5174、5175，这样本机开发不会直接报错，但如果你把地址写进了同事需要访问的文档或代理配置，就会连到旧端口上。加 --strictPort 即可让端口被占用时直接报错退出而不是悄悄换号：vite --strictPort 3000。局域网联调用 vite --host 0.0.0.0 让服务器监听所有网卡，默认只绑本机；若依赖预打包出了问题（旧版本依赖的 optimize 缓存损坏），用 vite --force 强制重建一次预打包。

为什么自定义的环境变量在浏览器里读到的是 undefined？

因为 Vite 只把带 VITE_ 前缀的变量暴露给客户端代码：写在 .env 里的 MY_API_URL 不会被打包进产物，必须命名为 VITE_API_URL，才能通过 import.meta.env.VITE_API_URL 读到。未加前缀的变量只在服务端或配置文件里可见，这是刻意的安全设计，避免密钥泄漏到前端。配套的还有内置变量 import.meta.env.MODE（development / production）、DEV 和 PROD 布尔值。需要按模式区分配置时用 vite build --mode staging，会加载 .env.staging；在 vite.config.ts 里可用 loadEnv(mode, process.env.cwd(), ) 自行加载。

打包后部署到子路径，静态资源全是 404 怎么解决？

原因是构建产物默认按站点根路径引用资源，部署到 /my-app/ 这类子目录时就对不上了。在 vite.config.ts 里设置 base: '/my-app/'，构建时的资源 URL 会带上该前缀，开发时用 vite --base 也能临时验证。相关配置还有 build.outDir 指定输出目录（默认 dist）、build.assetsDir 指定静态资源子目录（默认 assets）、build.emptyOutDir 在构建前清空输出目录以免残留旧文件，以及 build.target 设定目标浏览器版本。改完 base 后务必用 vite preview 确认一遍，它模拟生产环境，比看 dev server 可靠。

build.lib 和 build.ssr 两种模式分别产出什么？

build.ssr: true 生成的是服务端渲染用的产物——同一份源码渲染到服务端，HTML 由框架在服务端拼好后再下发，客户端负责注水；配合 ssrManifest: true 生成预加载清单，让客户端知道该预取哪些资源；ssr.external: ['vue'] 把依赖留在运行时外部引入不打进产物，ssr.noExternal: ['my-lib'] 则强制把某些依赖打进产物。build.lib: { entry: 'src/index.ts', name: 'MyLib' } 是库模式，产出可供别人 import 的包，build.lib.formats: ['es', 'cjs', 'umd'] 指定输出 ESM / CommonJS / UMD 三种格式以便兼容不同消费方。两者目的不同，不要混用。

构建产物越来越大，怎么定位是哪个依赖在膨胀？

Vite 本身不带分析能力，需要接入 rollup-plugin-visualizer，在 vite.config.ts 里以插件形式注册后执行一次构建，它会生成一份可交互的打包体积报告，列出每个模块的原始大小与打包后体积，能直接看出是某个 UI 库、某个语言的完整 locale 文件，还是某段被误引入的 polyfill 占了主要体积。定位后再从引入方式下手：改为按需导入，或换更轻的替代实现。注意 rollup-plugin-visualizer 的配置写法是 import { visualizer } from 'rollup-plugin-visualizer'，它作为一个 Rollup 插件工作，因此需要放进配置里而不是当成 Vite 专用插件。

官方参考来源

下方为命令对应的官方权威文档，供你核对最新用法与深入查阅。

Figma 帮助中心

由巧匠维护

公开更新于 2026年7月21日，内容持续校对官方文档。

联系我们

命令或描述有误？提交反馈、商务合作或产品建议都可发送邮件给我们。

联系我们

典型使用场景

项目创建与初始化 5

开发服务器 7

构建打包 7

配置选项 7

环境变量与模式 6

插件与集成 6

SSR 与库模式 6

参数矩阵

易错点与避坑指南

排障路径

命令示例

指定模板创建项目并起开发服务器

基础配置：子路径部署 + 资源目录 + 构建目标

多环境变量：VITE_ 前缀 + 按模式构建

库模式打包，输出 ESM/CJS/UMD

SSR：外部化 vue、强制打包自有库

常见坑与注意事项

提示

常见问题

相关速查表

分享

官方参考来源

由 巧匠 维护

联系我们

由巧匠维护