跳到主要内容

依赖预构建

当你第一次运行 vite 时,Vite 会在本地加载你的网站之前预构建你的项目依赖。默认情况下,它是自动且透明地完成的。

为什么要预构建

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

  1. CommonJS 和 UMD 兼容性: 在开发过程中,Vite 的开发服务器将所有代码都作为原生 ESM 提供。因此,Vite 必须首先将作为 CommonJS 或 UMD 发布的依赖项转换为 ESM。

    在转换 CommonJS 依赖项时,Vite 执行智能导入分析,以便对 CommonJS 模块的命名导入能够按预期工作,即使导出是动态分配的(例如 React)。

    js
    // works as expected
    import React, { useState } from 'react'
  2. 性能: Vite 将具有许多内部模块的 ESM 依赖项转换为单个模块,以提高后续页面加载性能。

    一些包将其 ES 模块构建作为许多单独的文件发布,这些文件相互导入。例如,lodash-es 具有 600 多个内部模块!当我们执行 import { debounce } from 'lodash-es' 时,浏览器会同时发出 600 多个 HTTP 请求!即使服务器处理这些请求没有问题,但大量的请求会在浏览器端造成网络拥塞,导致页面加载速度明显变慢。

    通过将 lodash-es 预构建成单个模块,我们现在只需要一个 HTTP 请求!

注意

依赖预构建仅适用于开发模式,并使用 esbuild 将依赖项转换为 ESM。在生产构建中,将改用 @rollup/plugin-commonjs

自动依赖发现

如果没有找到现有缓存,Vite 将抓取你的源代码并自动发现依赖导入(即期望从 node_modules 解析的“裸导入”),并将这些找到的导入用作预构建的入口点。预构建使用 esbuild 执行,因此通常非常快。

在服务器已经启动后,如果遇到尚未在缓存中的新依赖导入,Vite 将重新运行依赖项捆绑过程,并在需要时重新加载页面。

Monorepos 和链接的依赖项

在 monorepo 设置中,依赖项可能是来自同一仓库的链接包。Vite 会自动检测未从 node_modules 解析的依赖项,并将链接的依赖项视为源代码。它不会尝试捆绑链接的依赖项,而是会分析链接的依赖项的依赖项列表。

但是,这要求链接的依赖项以 ESM 形式导出。如果不是,你可以将依赖项添加到 optimizeDeps.includebuild.commonjsOptions.include 在你的配置中。

vite.config.js
js
export default 
defineConfig
({
optimizeDeps
: {
include
: ['linked-dep'],
},
build
: {
commonjsOptions
: {
include
: [/linked-dep/, /node_modules/],
}, }, })

当更改链接的依赖项时,使用 --force 命令行选项重新启动开发服务器以使更改生效。

自定义行为

默认的依赖项发现启发式方法可能并不总是理想的。如果你想显式地从列表中包含/排除依赖项,请使用 optimizeDeps 配置选项

optimizeDeps.includeoptimizeDeps.exclude 的典型用例是你有一个在源代码中无法直接发现的导入。例如,导入可能是插件转换的结果。这意味着 Vite 将无法在初始扫描中发现导入 - 它只能在浏览器请求文件并进行转换后才能发现它。这将导致服务器在服务器启动后立即重新捆绑。

includeexclude 都可以用来处理这种情况。如果依赖项很大(具有许多内部模块)或者依赖项是 CommonJS,那么你应该包含它;如果依赖项很小并且已经是有效的 ESM,你可以排除它并让浏览器直接加载它。

你还可以使用 optimizeDeps.esbuildOptions 选项进一步自定义 esbuild。例如,添加一个 esbuild 插件来处理依赖项中的特殊文件或更改 build target

缓存

文件系统缓存

Vite 将预构建的依赖项缓存在 node_modules/.vite 中。它基于以下几个来源确定是否需要重新运行预构建步骤:

  • 包管理器锁定文件内容,例如 package-lock.jsonyarn.lockpnpm-lock.yamlbun.lockb
  • 补丁文件夹修改时间。
  • 你的 vite.config.js 中的相关字段(如果存在)。
  • NODE_ENV 值。

只有当上述其中一项发生更改时,才需要重新运行预构建步骤。

如果由于某种原因你想强制 Vite 重新捆绑依赖项,你可以使用 --force 命令行选项启动开发服务器,或者手动删除 node_modules/.vite 缓存目录。

浏览器缓存

已解析的依赖项请求会使用 HTTP 标头 max-age=31536000,immutable 强缓存,以提高开发期间的页面重新加载性能。一旦缓存,这些请求将永远不会再次访问开发服务器。如果安装了不同的版本(如你的包管理器锁定文件中所反映的那样),它们会自动通过附加的版本查询来失效。如果你想通过进行本地编辑来调试你的依赖项,你可以:

  1. 通过你的浏览器开发者工具的网络选项卡暂时禁用缓存。
  2. 使用 --force 标志重新启动 Vite 开发服务器以重新捆绑依赖项。
  3. 重新加载页面。

在 MIT 许可证下发布。(083ff36d)