总览

Vite（法语意为 "快速的"，发音 /vit/[图片上传失败...(image-7771a7-1647833168481)] ，发音同 "veet"）是一种新型前端构建工具，能够显著提升前端开发体验。它主要由两部分组成：

• 一个开发服务器，它基于 原生 ES 模块 提供了 丰富的内建功能，如速度快到惊人的 模块热更新（HMR）。

• 一套构建指令，它使用 Rollup 打包你的代码，并且它是预配置的，可输出用于生产环境的高度优化过的静态资源。

Vite 意在提供开箱即用的配置，同时它的 插件 API 和 JavaScript API 带来了高度的可扩展性，并有完整的类型支持。
你可以在 为什么选 Vite 中了解更多关于项目的设计初衷。

Vue 第一优先级支持

Vite 最初是作为 Vue.js 开发工具的未来基础而创建的。尽管 Vite 2.0 版本完全不依赖于任何框架，但官方 Vue 插件仍然对 Vue 的单文件组件格式提供了第一优先级的支持，涵盖了所有高级特性，如模板资源引用解析、<script setup>，<style module>，自定义块等等。除此之外，Vite 还对 Vue 单文件组件提供了细粒度的 HMR。举个例子，更新一个单文件组件的 <template> 或 <style> 会执行不重置其状态的热更新。

浏览器支持

• 默认的构建目标浏览器是能 在 script 标签上支持原生 ESM 和 原生 ESM 动态导入。传统浏览器可以通过官方插件 @vitejs/plugin-legacy 支持 —— 查看 构建生产版本 章节获取更多细节。

搭建第一个 Vite 项目

兼容性注意, Vite 需要 Node.js 版本 >= 12.0.0。

### npm 7+, 需要额外的双横线：
npm init vite@latest my-vue-app -- --template vue

查看 create-vite 以获取每个模板的更多细节：vanilla，vanilla-ts，vue，vue-ts，react，react-ts，preact，preact-ts，lit，lit-ts，svelte，svelte-ts。

index.html 与项目根目录

Vite 将 index.html 视为源码和模块图的一部分。Vite 解析 <script type="module" src="..."> ，这个标签指向你的 JavaScript 源码。甚至内联引入 JavaScript 的 <script type="module"> 和引用 CSS 的 <link href> 也能利用 Vite 特有的功能被解析。另外，index.html 中的 URL 将被自动转换，因此不再需要 %PUBLIC_URL% 占位符了。

Vite 也支持多个 .html 作入口点的 多页面应用模式。

指定替代根目录

vite 以当前工作目录作为根目录启动开发服务器。你也可以通过 vite serve some/sub/dir 来指定一个替代的根目录。

在安装了 Vite 的项目中，可以在 npm scripts 中使用 vite 可执行文件，或者直接使用 npx vite 运行它。下面是通过脚手架创建的 Vite 项目中默认的 npm scripts：

### package.json
{
  "name": "vite-henrypt",
  "private": true,
  "version": "0.0.0",
  "scripts": {
    "dev": "vite",  # 启动开发服务器，别名：`vite dev`, `vite serve`
    "build": "vite build", # 为生产环境构建产物
    "preview": "vite preview" # 本地预览生产构建产物
  },
  "dependencies": {
    "vue": "^3.2.25"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^2.2.0",
    "vite": "^2.8.0"
  }
}

可以指定额外的命令行选项，如 --port 或 --https。运行 npx vite --help 获得完整的命令行选项列表。

功能

对非常基础的使用来说，使用 Vite 开发和使用一个静态文件服务器并没有太大区别。然而，Vite 还通过原生 ESM 导入提供了许多主要用于打包场景的增强功能。

NPM 依赖解析和预构建#

原生 ES 导入不支持下面这样的裸模块导入：import { add } from 'my-dep'
上面的代码会在浏览器中抛出一个错误。Vite 将会检测到所有被加载的源文件中的此类裸模块导入，并执行以下操作:

1. 预构建 它们可以提高页面加载速度，并将 CommonJS / UMD 转换为 ESM 格式。预构建这一步由 esbuild 执行，这使得 Vite 的冷启动时间比任何基于 JavaScript 的打包器都要快得多。

2. 重写导入为合法的 URL，例如 /node_modules/.vite/my-dep.js?v=f3sf2ebd 以便浏览器能够正确导入它们。

依赖是强缓存的

Vite 通过 HTTP 头来缓存请求得到的依赖，所以如果你想要编辑或调试一个依赖，请按照 这里 的步骤操作。

模块热重载

Vite 提供了一套原生 ESM 的 HMR API。 具有 HMR 功能的框架可以利用该 API 提供即时、准确的更新，而无需重新加载页面或清除应用程序状态。Vite 内置了 HMR 到 Vue 单文件组件（SFC） 和 React Fast Refresh 中。也通过 @prefresh/vite 对 Preact 实现了官方集成。

注意，你不需要手动设置这些 —— 当你通过 create-vite 创建应用程序时，所选模板已经为你预先配置了这些。

TypeScript#

略过

Vue

Vite 为 Vue 提供第一优先级支持：

• Vue 3 单文件组件支持：@vitejs/plugin-vue
• Vue 3 JSX 支持：@vitejs/plugin-vue-jsx
• Vue 2 支持：underfin/vite-plugin-vue2

JSX

略过

CSS

CSS 预处理器支持
Vite 为 Sass and Less 提供了更精细化的支持，包括改进 @import 解析（可使用别名与 npm 依赖）和 提供 url() 内联引入与变基。

导入 .css 文件将会把内容插入到 <style> 标签中，同时也带有 HMR 支持。也能够以字符串的形式检索处理后的、作为其模块默认导出的 CSS。

1. @import 内联和变基
   Vite 通过 postcss-import 预配置支持了 CSS @import 内联，Vite 的路径别名也遵从 CSS @import。换句话说，所有 CSS url() 引用，即使导入的文件在不同的目录中，也总是自动变基，以确保正确性。

2. PostCSS
   如果项目包含有效的 PostCSS 配置 (任何受 postcss-load-config 支持的格式，例如 postcss.config.js)，它将会自动应用于所有已导入的 CSS。

3. CSS Modules
   任何以 .module.css 为后缀名的 CSS 文件都被认为是一个 CSS modules 文件。

4. CSS 预处理器
   由于 Vite 的目标仅为现代浏览器，因此建议使用原生 CSS 变量和实现 CSSWG 草案的 PostCSS 插件（例如 postcss-nesting）来编写简单的、符合未来标准的 CSS。

话虽如此，但 Vite 也同时提供了对 .scss, .sass, .less, .styl 和 .stylus 文件的内置支持。没有必要为它们安装特定的 Vite 插件，但必须安装相应的预处理器依赖：

# .scss and .sass
npm install -D sass

# .less
npm install -D less

# .styl and .stylus
npm install -D stylus

如果是用的是单文件组件，可以通过 <style lang="sass">（或其他预处理器）自动开启。

静态资源处理

导入一个静态资源会返回解析后的 URL：

import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl

添加一些特殊的查询参数可以更改资源被引入的方式：

// 显式加载资源为一个 URL
import assetAsURL from './asset.js?url'

// 以字符串形式加载资源
import assetAsString from './shader.glsl?raw'

// 加载为 Web Worker
import Worker from './worker.js?worker'

// 在构建时 Web Worker 内联为 base64 字符串
import InlineWorker from './worker.js?worker&inline'

更多细节请见 静态资源处理。

JSON

JSON 可以被直接导入 —— 同样支持具名导入：

// 导入整个对象
import json from './example.json'
// 对一个根字段使用具名导入 —— 有效帮助 Tree Shaking！
import { field } from './example.json'

Glob 导入

Vite 支持使用特殊的 import.meta.glob 函数从文件系统导入多个模块：
const modules = import.meta.glob('./dir/*.js')
以上将会被转译为下面的样子：

// vite 生成的代码
const modules = {
  './dir/foo.js': () => import('./dir/foo.js'),
  './dir/bar.js': () => import('./dir/bar.js')
}

你可以遍历 modules 对象的 key 值来访问相应的模块：

for (const path in modules) {
  modules[path]().then((mod) => {
    console.log(path, mod)
  })
}

WebAssembly

预编译的 .wasm 文件可以直接被导入 —— 默认导出一个函数，返回值为所导出 wasm 实例对象的 Promise：...

Web Worker

一个 web worker 脚本可以直接通过添加一个 ?worker 或 ? shared worker 查询参数来导入。默认导出一个自定义的 worker 构造器：

import MyWorker from './worker?worker'
const worker = new MyWorker()

注意，在开发过程中，这依赖于浏览器原生支持，目前只在 Chrome 中适用，而在生产版本中，它已经被编译掉了。

构建优化

下面所罗列的功能会自动应用为构建过程的一部分，除非你想禁用它们，否则没有必要显式配置。

1. CSS 代码分割
2. 预加载指令生成
3. 异步 Chunk 加载优化
   在无优化的情境下，当异步 chunk A 被导入时，浏览器将必须请求和解析 A，然后它才能弄清楚它也需要共用 chunk C。这会导致额外的网络往返：Entry ---> A ---> C
   Vite 将使用一个预加载步骤自动重写代码，来分割动态导入调用，以实现当 A 被请求时，C 也将 同时 被请求：Entry ---> (A + C)
   C 也可能有更深的导入，在未优化的场景中，这会导致更多的网络往返。Vite 的优化会跟踪所有的直接导入，无论导入的深度如何，都能够完全消除不必要的往返。

使用插件

Vite 可以使用插件进行扩展，这得益于 Rollup 优秀的插件接口设计和一部分 Vite 独有的额外选项。这意味着 Vite 用户可以利用 Rollup 插件的强大生态系统，同时根据需要也能够扩展开发服务器和 SSR 功能。

添加一个插件

若要使用一个插件，需要将它添加到项目的 devDependencies 并在 vite.config.js 配置文件中的 plugins 数组中引入它。例如，要想为传统浏览器提供支持，可以按下面这样使用官方插件 @vitejs/plugin-legacy：
$ npm i -D @vitejs/plugin-legacy

// vite.config.js
import legacy from '@vitejs/plugin-legacy'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    legacy({
      targets: ['defaults', 'not IE 11']
    })
  ]
})

查找插件

查看 Plugins 章节 获取官方插件信息。社区插件列表请参见 awesome-vite。而对于兼容的 Rollup 插件，请查看 Vite Rollup 插件 获取一个带使用说明的兼容 Rollup 官方插件列表，若列表中没有找到，则请参阅 Rollup 插件兼容性章节。

你也可以使用此 npm Vite 插件搜索链接 来找到一些遵循了 推荐约定 的 Vite 插件，或者通过 npm Rollup 插件搜索链接 获取 Rollup 插件。

强制插件排序

为了与某些 Rollup 插件兼容，可能需要强制执行插件的顺序，或者只在构建时使用。这应该是 Vite 插件的实现细节。可以使用 enforce 修饰符来强制插件的位置:

• pre：在 Vite 核心插件之前调用该插件
• 默认：在 Vite 核心插件之后调用该插件
• post：在 Vite 构建插件之后调用该插件

// vite.config.js
import image from '@rollup/plugin-image'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    {
      ...image(),
      enforce: 'pre'
    }
  ]
})

查看 Plugins API Guide 获取细节信息，并在 Vite Rollup 插件 兼容性列表中注意 enforce 标签和流行插件的使用说明。

按需应用

默认情况下插件在开发 (serve) 和生产 (build) 模式中都会调用。如果插件在服务或构建期间按需使用，请使用 apply 属性指明它们仅在 'build' 或 'serve' 模式时调用：

// vite.config.js
import typescript2 from 'rollup-plugin-typescript2'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    {
      ...typescript2(),
      apply: 'build'
    }
  ]
})

创建插件

阅读 插件 API 指引 文档了解如何创建插件。

依赖预构建

image.png

原因

这就是 Vite 执行的所谓的“依赖预构建”。这个过程有两个目的:

1. CommonJS 和 UMD 兼容性
2. 性能
   Vite 将有许多内部模块的 ESM 依赖关系转换为单个模块，以提高后续页面加载性能。

自动依赖搜寻

如果没有找到相应的缓存，Vite 将抓取你的源码，并自动寻找引入的依赖项（即 "bare import"，表示期望从 node_modules 解析），并将这些依赖项作为预构建包的入口点。预构建通过 esbuild 执行，所以它通常非常快。在服务器已经启动之后，如果遇到一个新的依赖关系导入，而这个依赖关系还没有在缓存中，Vite 将重新运行依赖构建进程并重新加载页面。

Monorepo 和链接依赖

略过

自定义行为

默认的依赖项发现为启发式可能并不总是可取的。在你想要显式地从列表中包含/排除依赖项的情况下, 请使用 optimizeDeps 配置项。

缓存

1. 文件系统缓存
   Vite 会将预构建的依赖缓存到 node_modules/.vite。它根据几个源来决定是否需要重新运行预构建步骤:

• package.json 中的 dependencies 列表
• 包管理器的 lockfile，例如 package-lock.json, yarn.lock，或者 pnpm-lock.yaml
• 可能在 vite.config.js 相关字段中配置过的
  只有在上述其中一项发生更改时，才需要重新运行预构建。

如果出于某些原因，你想要强制 Vite 重新构建依赖，你可以用 --force 命令行选项启动开发服务器，或者手动删除 node_modules/.vite 目录。

2. 浏览器缓存
   解析后的依赖请求会以 HTTP 头 max-age=31536000,immutable 强缓存，以提高在开发时的页面重载性能。一旦被缓存，这些请求将永远不会再到达开发服务器。如果安装了不同的版本（这反映在包管理器的 lockfile 中），则附加的版本 query 会自动使它们失效。如果你想通过本地编辑来调试依赖项，你可以:

• 通过浏览器调试工具的 Network 选项卡暂时禁用缓存；
• 重启 Vite dev server，并添加 --force 命令以重新构建依赖；
• 重新载入页面。

静态资源处理

• 相关: 公共基础路径
• 相关: assetsInclude 配置项

将资源引入为 URL

服务时引入一个静态资源会返回解析后的公共路径：

import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl

例如，imgUrl 在开发时会是 /img.png，在生产构建后会是 /assets/img.2d8efhg.png。
行为类似于 Webpack 的 file-loader。区别在于导入既可以使用绝对公共路径（基于开发期间的项目根路径），也可以使用相对路径。

• url() 在 CSS 中的引用也以同样的方式处理。
• 如果 Vite 使用了 Vue 插件，Vue SFC 模板中的资源引用都将自动转换为导入。
• 常见的图像、媒体和字体文件类型被自动检测为资源。你可以使用 assetsInclude 选项 扩展内部列表。
• 引用的资源作为构建资源图的一部分包括在内，将生成散列文件名，并可以由插件进行处理以进行优化。
• 较小的资源体积小于 assetsInlineLimit 选项值 则会被内联为 base64 data URL。

显式 URL 引入

未被包含在内部列表或 assetsInclude 中的资源，可以使用 ?url 后缀显式导入为一个 URL。这十分有用，例如，要导入 Houdini Paint Worklets 时：

import workletURL from 'extra-scalloped-border/worklet.js?url'
CSS.paintWorklet.addModule(workletURL)

// 显式加载资源为一个 URL
import assetAsURL from './asset.js?url'

// 以字符串形式加载资源
import assetAsString from './shader.glsl?raw'

// 在生产构建中将会分离出 chunk
import Worker from './shader.js?worker'
const worker = new Worker()

// sharedworker
import SharedWorker from './shader.js?sharedworker'
const sharedWorker = new SharedWorker()

// 内联为 base64 字符串
import InlineWorker from './shader.js?worker&inline'

查看 Web Worker 小节 获取更多细节。

public 目录

如果你有下列这些资源：

• 不会被源码引用（例如 robots.txt）
• 必须保持原有文件名（没有经过 hash）
• ...或者你压根不想引入该资源，只是想得到其 URL。

那么你可以将该资源放在指定的 public 目录中，它应位于你的项目根目录。该目录中的资源在开发时能直接通过 / 根路径访问到，并且打包时会被完整复制到目标目录的根目录下。

目录默认是 <root>/public，但可以通过 publicDir 选项 来配置。
请注意：

• 引入 public 中的资源永远应该使用根绝对路径, 举例public/icon.png 应该在源码中被引用为 /icon.png。
• public 中的资源不应该被 JavaScript 文件引用。

new URL(url, import.meta.url)

import.meta.url 是一个 ESM 的原生功能，会暴露当前模块的 URL。将它与原生的 URL 构造器 组合使用，在一个 JavaScript 模块中，通过相对路径我们就能得到一个被完整解析的静态资源 URL：

const imgUrl = new URL('./img.png', import.meta.url).href
document.getElementById('hero-img').src = imgUrl

这在现代浏览器中能够原生使用 - 实际上，Vite 并不需要在开发阶段处理这些代码！

这个模式同样还可以通过字符串模板支持动态 URL：

function getImageUrl(name) {
  return new URL(`./dir/${name}.png`, import.meta.url).href
}

在生产构建时，Vite 才会进行必要的转换保证 URL 在打包和资源哈希后仍指向正确的地址。

注意：无法在 SSR 中使用

如果你正在以服务端渲染模式使用 Vite 则此模式不支持，因为 import.meta.url 在浏览器和 Node.js 中有不同的语义。服务端的产物也无法预先确定客户端主机 URL。

构建生产版本

当需要将应用部署到生产环境时，只需运行 vite build 命令。默认情况下，它使用 <root>/index.html 作为其构建入口点，并生成能够静态部署的应用程序包。请查阅 部署静态站点 获取常见服务的部署指引。

浏览器兼容性

用于生产环境的构建包会假设目标浏览器支持现代 JavaScript 语法。默认情况下，Vite 的目标浏览器是指能够 支持原生 ESM script 标签 和 支持原生 ESM 动态导入 的。作为参考，Vite 使用这个 browserslist 作为查询标准：defaults and supports es6-module and supports es6-module-dynamic-import, not opera > 0, not samsung > 0, not and_qq > 0
你也可以通过 build.target 配置项 指定构建目标，最低支持 es2015。

请注意，默认情况下 Vite 只处理语法转译，且 默认不包含任何 polyfill。你可以前往 Polyfill.io 查看，这是一个基于用户浏览器 User-Agent 字符串自动生成 polyfill 包的服务。

传统浏览器可以通过插件 @vitejs/plugin-legacy 来支持，它将自动生成传统版本的 chunk 及与其相对应 ES 语言特性方面的 polyfill。兼容版的 chunk 只会在不支持原生 ESM 的浏览器中进行按需加载。

公共基础路径

• 相关内容：静态资源处理

如果你需要在嵌套的公共路径下部署项目，只需指定 base 配置项，然后所有资源的路径都将据此配置重写。这个选项也可以通过命令行参数指定，例如 vite build --base=/my/public/path/。

由 JS 引入的资源 URL，CSS 中的 url() 引用以及 .html 文件中引用的资源在构建过程中都会自动调整，以适配此选项。

当然，情况也有例外，当访问过程中需要使用动态连接的 url 时，可以使用全局注入的 import.<wbr style="box-sizing: border-box;">meta.env.BASE_URL 变量，它的值为公共基础路径。注意，这个变量在构建时会被静态替换，因此，它必须按 import.<wbr style="box-sizing: border-box;">meta.env.BASE_URL 的原样出现（例如 import.<wbr style="box-sizing: border-box;">meta.env['BASE_URL'] 是无效的）

自定义构建

略过

文件变化时重新构建

略过

多页面应用模式

假设你有下面这样的项目文件结构

├── package.json
├── vite.config.js
├── index.html
├── main.js
└── nested
    ├── index.html
    └── nested.js

在开发过程中，简单地导航或链接到 /nested/ - 将会按预期工作，与正常的静态文件服务器表现一致。
在构建过程中，你只需指定多个 .html 文件作为入口点即可：
// vite.config.js
const { resolve } = require('path')
const { defineConfig } = require('vite')

module.exports = defineConfig({
  build: {
    rollupOptions: {
      input: {
        main: resolve(__dirname, 'index.html'),
        nested: resolve(__dirname, 'nested/index.html')
      }
    }
  }
})

如果你指定了另一个根目录，请记住，在解析输入路径时，__dirname 的值将仍然是 vite.config.js 文件所在的目录。因此，你需要把对应入口文件的 root 的路径添加到 resolve 的参数中。

库模式

当你开发面向浏览器的库时，你可能会将大部分时间花在该库的测试/演示页面上。在 Vite 中你可以使用 index.html 获得如丝般顺滑的开发体验。
略过

部署静态站点

本指南建立在以下几个假设基础之上：

• 你正在使用的是默认的构建输出路径（dist）。这个路径 可以通过 build.outDir 更改，在这种情况下，你可以从这篇指南中找到出所需的指引。
• 你正在使用 NPM；或者 Yarn 等其他可以运行下面的脚本指令的包管理工具。
• Vite 已作为一个本地开发依赖（dev dependency）安装在你的项目中，并且你已经配置好了如下的 npm scripts：

{
  "scripts": {
    "build": "vite build",
    "preview": "vite preview"
  }
}

值得注意的是 vite preview 用作预览本地构建，而不应直接作为生产服务器。

注意
本篇指南提供了部署 Vite 静态站点的说明。Vite 也对服务端渲染（SSR）有了实验性的支持。SSR 是指支持在 Node 中运行相应应用的前端框架，预渲染成 HTML，最后在客户端激活（hydrate）。查看 SSR 指南 了解更多细节。另一方面，如果你在寻找与传统服务端框架集成的方式，那么请查看 后端集成 章节。

构建应用

你可以运行 npm run build 命令来执行应用的构建。默认情况下，构建会输出到 dist 文件夹中。你可以部署这个 dist 文件夹到任何你喜欢的平台。

本地测试应用

当你构建完成应用后，你可以通过运行 npm run preview 命令，在本地测试该应用。
vite preview 命令会在本地启动一个静态 Web 服务器，将 dist 文件夹运行在 http://localhost:5000。这样在本地环境下查看该构建产物是否正常可用就方便了。
你可以通过 --port 参数来配置服务的运行端口。package.json { "scripts": { "preview": "vite preview --port 8080" } }

GitHub Pages

部署

腾讯云－Webify

1. 开通云托管
   登录腾讯云https://webify.cloudbase.net/, 我是用微信登录的，实用认证后开启服务，“新建应用”
   https://console.cloud.tencent.com/webify/index
   
   image.png
   
   应用创建之后，等待构建、部署完毕，便可以通过应用的默认域名（xxx.app.tcloudbase.com）来访问应用。
   我的是https://vite-henrypt-0gitm56jd2697f0e-1310395618.ap-shanghai.app.tcloudbase.com/
   注：创建云托管成功不久，我的信息就被卖了，有人给我打电话问我注册云托管，要不要买服务器！

2. 使用xxx.sh脚本（测试没成功）
   在你的项目中，创建一个 deploy.sh 脚本，包含以下内容（注意高亮的行，按需使用），运行脚本来部署站点：

#!/usr/bin/env sh

# 发生错误时终止
set -e

# 构建
npm run build

# 进入构建文件夹
cd dist

# 如果你要部署到自定义域名
# echo 'www.example.com' > CNAME

# git init
git add -A
git commit -m "deploy"

# 如果你要部署在 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git main

# 如果你要部署在 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:branch-test1   [master是默认主分支; branch-test1是子分支]
git push -f https://gitee.com/henrypt1213/vite-henrypt master:branch-test1
 
cd -

*** .sh文件执行 ***

windows下vscode运行shell脚本

image.png

image.png

环境变量和模式

环境变量

Vite 在一个特殊的 import.meta.env 对象上暴露环境变量。这里有一些在所有情况下都可以使用的内建变量：

• import.meta.env.MODE: {string} 应用运行的模式。

• import.meta.env.BASE_URL: {string} 部署应用时的基本 URL。他由base 配置项决定。

• import.meta.env.PROD: {boolean} 应用是否运行在生产环境。

• import.meta.env.DEV: {boolean} 应用是否运行在开发环境 (永远与 import.<wbr style="box-sizing: border-box;">meta.env.PROD相反)。

生产环境替换

在生产环境中，这些环境变量会在构建时被静态替换，因此，在引用它们时请使用完全静态的字符串。动态的 key 将无法生效。例如，动态 key 取值 import.meta.env[key] 是无效的。
它还将替换出现在 JavaScript 和 Vue 模板中的字符串。这本应是非常少见的，但也可能是不小心为之的。在这种情况下你可能会看到类似 Missing Semicolon 或 Unexpected token 等错误，例如当 "process.env.NODE_ENV" 被替换为 ""development": "。有一些方法可以避免这个问题：

• 对于 JavaScript 字符串，你可以使用 unicode 零宽度空格 \u200b (一个看不见的分隔符)来分割这个字符串，例如： 'import.meta.env.MODE'。

• 对于 Vue 模板或其他编译到 JavaScript 字符串的 HTML，你可以使用 <wbr> 标签，例如：import.meta.env.MODE。
  略过

服务端渲染

实验性
SSR 支持还处于试验阶段，你可能会遇到 bug 和不受支持的用例。请考虑你可能承担的风险。

注意
SSR 特别指支持在 Node.js 中运行相同应用程序的前端框架（例如 React、Preact、Vue 和 Svelte），将其预渲染成 HTML，最后在客户端进行注水化处理。如果你正在寻找与传统服务器端框架的集成，请查看 后端集成指南。
下面的指南还假定你在选择的框架中有使用 SSR 的经验，并且只关注特定于 Vite 的集成细节。

示例项目

Vite 为服务端渲染（SSR）提供了内建支持。这里的 Vite 范例包含了 Vue 3 和 React 的 SSR 设置示例，可以作为本指南的参考：

• Vue 3
• React

源码结构

一个典型的 SSR 应用应该有如下的源文件结构：

- index.html
- src/
  - main.js          # 导出环境无关的（通用的）应用代码
  - entry-client.js  # 将应用挂载到一个 DOM 元素上
  - entry-server.js  # 使用某框架的 SSR API 渲染该应用

index.html 将需要引用 entry-client.js 并包含一个占位标记供给服务端渲染时注入：

<div id="app"><!--ssr-outlet--></div>
<script type="module" src="/src/entry-client.js"></script>

你可以使用任何你喜欢的占位标记来替代 ，只要它能够被正确替换。

情景逻辑

如果需要执行 SSR 和客户端间情景逻辑，可以使用：

if ( import.meta.env.SSR ) {
  // ... 仅在服务端执行的逻辑
}

这是在构建过程中被静态替换的，因此它将允许对未使用的条件分支进行摇树优化。

设置开发服务器

在构建 SSR 应用程序时，你可能希望完全控制主服务器，并将 Vite 与生产环境脱钩。因此，建议以中间件模式使用 Vite。下面是一个关于 express 的例子：

# server.js
const fs = require('fs')
const path = require('path')
const express = require('express')
const { createServer: createViteServer } = require('vite')

async function createServer() {
  const app = express()

  // 以中间件模式创建 Vite 应用，这将禁用 Vite 自身的 HTML 服务逻辑
  // 并让上级服务器接管控制
  //
  // 如果你想使用 Vite 自己的 HTML 服务逻辑（将 Vite 作为
  // 一个开发中间件来使用），那么这里请用 'html'
  const vite = await createViteServer({
    server: { middlewareMode: 'ssr' }
  })
  // 使用 vite 的 Connect 实例作为中间件
  app.use(vite.middlewares)

  app.use('*', async (req, res) => {
    // 服务 index.html - 下面我们来处理这个问题
  })

  app.listen(3000)
}

createServer()

这里 vite 是 ViteDevServer 的一个实例。vite.middlewares 是一个 Connect 实例，它可以在任何一个兼容 connect 的 Node.js 框架中被用作一个中间件。

下一步是实现 * 处理程序供给服务端渲染的 HTML：

app.use('*', async (req, res) => {
  const url = req.originalUrl

  try {
    // 1. 读取 index.html
    let template = fs.readFileSync(
      path.resolve(__dirname, 'index.html'),
      'utf-8'
    )

    // 2. 应用 Vite HTML 转换。这将会注入 Vite HMR 客户端，
    //    同时也会从 Vite 插件应用 HTML 转换。
    //    例如：@vitejs/plugin-react-refresh 中的 global preambles
    template = await vite.transformIndexHtml(url, template)

    // 3. 加载服务器入口。vite.ssrLoadModule 将自动转换
    //    你的 ESM 源码使之可以在 Node.js 中运行！无需打包
    //    并提供类似 HMR 的根据情况随时失效。
    const { render } = await vite.ssrLoadModule('/src/entry-server.js')

    // 4. 渲染应用的 HTML。这假设 entry-server.js 导出的 `render`
    //    函数调用了适当的 SSR 框架 API。
    //    例如 ReactDOMServer.renderToString()
    const appHtml = await render(url)

    // 5. 注入渲染后的应用程序 HTML 到模板中。
    const html = template.replace(`<!--ssr-outlet-->`, appHtml)

    // 6. 返回渲染后的 HTML。
    res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
  } catch (e) {
    // 如果捕获到了一个错误，让 Vite 来修复该堆栈，这样它就可以映射回
    // 你的实际源码中。
    vite.ssrFixStacktrace(e)
    console.error(e)
    res.status(500).end(e.message)
  }
})

package.json 中的 dev 脚本也应该相应地改变，使用服务器脚本：

"scripts": {
-   "dev": "vite"
+   "dev": "node server"
  }

生产环境构建

为了将 SSR 项目交付生产，我们需要：

1. 正常生成一个客户端构建；
2. 再生成一个 SSR 构建，使其通过 require() 直接加载，这样便无需再使用 Vite 的 ssrLoadModule；
   package.json 中的脚本应该看起来像这样：

{
  "scripts": {
    "dev": "node server",
    "build:client": "vite build --outDir dist/client",
    "build:server": "vite build --outDir dist/server --ssr src/entry-server.js "
  }
}

注意使用 --ssr 标志表明这将会是一个 SSR 构建。同时需要指定 SSR 的入口。

接着，在 server.js 中，通过 process.env.NODE_ENV 条件分支，需要添加一些用于生产环境的特定逻辑：

• 使用 dist/client/index.html 作为模板，而不是根目录的 index.html，因为前者包含了到客户端构建的正确资源链接。

• 使用 require('./dist/server/entry-server.js') ，而不是 await vite.ssrLoadModule('/src/entry-server.js')（前者是 SSR 构建后的最终结果）。

• 将 vite 开发服务器的创建和所有使用都移到 dev-only 条件分支后面，然后添加静态文件服务中间件来服务 dist/client 中的文件。

可以在此参考 Vue 和 React 的设置范例。

生成预加载指令

略过

预渲染 / SSG

如果预先知道某些路由所需的路由和数据，我们可以使用与生产环境 SSR 相同的逻辑将这些路由预先渲染到静态 HTML 中。这也被视为一种静态站点生成（SSG）的形式。查看 示例渲染代码 获取有效示例。

SSR 外部化

略过

SSR 专有插件逻辑

一些框架，如 Vue 或 Svelte，会根据客户端渲染和服务端渲染的区别，将组件编译成不同的格式。可以向以下的插件钩子中，给 Vite 传递额外的 options 对象，对象中包含 ssr 属性来支持根据情景转换：

• resolveId
• load
• transform
  ...

SSR Target

SSR 构建的默认目标为 node 环境，但你也可以让服务运行在 Web Worker 上。每个平台的打包条目解析是不同的。你可以将ssr.target 设置为 webworker，以将目标配置为 Web Worker。

SSR Bundle

在某些如 webworker 运行时等特殊情况中，你可能想要将你的 SSR 打包成单个 JavaScript 文件。你可以通过设置 ssr.noExternal 为 true 来启用这个行为。这将会做两件事：

• 将所有依赖视为 noExternal（非外部化）
• 若任何 Node.js 内置内容被引入，将抛出一个错误

后端集成

如果你想使用传统的后端（如 Rails, Laravel）来服务 HTML，但使用 Vite 来服务其他资源，可以查看在 Awesome Vite 上的已有的后端集成列表。

如果你需要自定义集成，你可以按照本指南的步骤配置它：
略过

与其它非打包解决方案比较

略过

插件 API

略过

HMR API

注意
这里是客户端 HMR API。若要在插件中处理 HMR 更新，详见 handleHotUpdate。
手动 HMR API 主要用于框架和工具作者。作为最终用户，HMR 可能已经在特定于框架的启动器模板中为你处理过了。

Vite 通过特殊的 import.meta.hot 对象暴露手动 HMR API。
略过

JavaScript API

Vite 的 JavaScript API 是完全类型化的，我们推荐使用 TypeScript 或者在 VSCode 中启用 JS 类型检查来利用智能提示和类型校验。

createServer 类型签名：

InlineConfig#

ViteDevServer

build

preview

resolveConfig

transformWithEsbuild

配置 Vite

配置文件解析

当以命令行方式运行 vite 时，Vite 会自动解析 项目根目录 下名为 vite.config.js 的文件

配置智能提示

因为 Vite 本身附带 Typescript 类型，所以你可以通过 IDE 和 jsdoc 的配合来实现智能提示

情景配置

如果配置文件需要基于（dev/serve 或 build）命令或者不同的 模式 来决定选项，则可以选择导出这样一个函数

异步配置

共享配置

vite.config.js的全部配置都在这里

开发服务器选项

• • server.host
  • server.port
  • server.strictPort
  • server.https
  • server.open
  • server.proxy
  • server.cors
  • server.force
  • server.hmr
  • server.watch
  • server.middlewareMode
  • server.fs.strict
  • server.fs.allow
  • server.fs.deny
  • server.origin

构建选项

预览选项

依赖优化选项

SSR 选项

插件

官方插件#

@vitejs/plugin-vue#

• 提供 Vue 3 单文件组件支持

@vitejs/plugin-vue-jsx#

• 提供 Vue 3 JSX 支持（通过 专用的 Babel 转换插件）。

@vitejs/plugin-react#

• 提供完整的 React 支持

@vitejs/plugin-legacy#

• 为打包后的文件提供传统浏览器兼容性支持

Rollup 插件

Vite 插件 是 Rollup 插件接口的一种扩展。查看 Rollup 插件兼容性章节 获取更多信息。