Vite build.modulePreload 怎样控制预加载依赖

如果页面使用了动态 import()，Vite 会在生产构建时为相关 chunk 计算需要预加载的依赖。想控制这件事，先不要把所有问题都归到一个开关上：build.modulePreload 既能控制 polyfill，也能通过实验性的 resolveDependencies 回调调整依赖列表。

官方地址：https://vite.dev/config/build-options

普通应用优先保留默认自动计算；只是不想注入 polyfill 时使用 { polyfill: false }；确实需要过滤或改写预加载路径时，再使用 resolveDependencies。回调返回值必须是相对于 build.outDir 的路径，且该能力在 Vite 文档中仍标为 experimental。

先区分 polyfill 和依赖列表

build.modulePreload 的默认值是一个启用 polyfill 的配置对象。polyfill 解决的是不支持原生动态导入的浏览器兼容问题；预加载依赖列表解决的是某个动态 chunk 还需要哪些资源。两者相关，但不是同一个控制点。

默认情况下，Vite 会在每个 index.html 入口对应的代理模块中注入 module preload polyfill，并根据动态导入关系计算依赖。如果项目采用非 HTML 自定义入口，还需要在自定义入口手动导入 vite/modulepreload-polyfill。Library Mode 不适用这套 polyfill 注入逻辑。

用默认配置保持自动预加载

如果没有明确的资源路径改写需求，推荐先使用最小配置。它让 Vite 继续负责依赖计算，减少手动维护构建产物的成本。

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    modulePreload: {
      // 保留默认 polyfill，让 Vite 自动计算动态导入依赖
      polyfill: true
    }
  }
})

也可以省略整个 modulePreload 配置，因为默认行为就是启用 polyfill 并自动生成依赖列表。对于常规单页应用，这通常是最稳妥的选择。

只关闭 polyfill，不要误伤依赖计算

如果目标浏览器已经由项目的兼容策略保证支持原生动态导入，可以只关闭 polyfill。这样并不等于关闭 Vite 对预加载依赖的计算。

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    modulePreload: {
      // 只关闭兼容层注入，不改变依赖列表的自动计算
      polyfill: false
    }
  }
})

这一配置适合已经明确控制浏览器范围的应用。若项目仍需支持不具备原生动态导入能力的环境，关闭 polyfill 前应先确认兼容方案，否则可能出现入口能加载、异步 chunk 却无法执行的情况。

用 resolveDependencies 过滤候选项

当默认列表包含不希望提前加载的资源时，可以使用 resolveDependencies。它会针对动态导入得到依赖候选数组，并把 url、deps、hostId 和 hostType 交给回调。返回的新数组可以过滤候选项，也可以调整路径，但结果必须是相对于 build.outDir 的路径。

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    modulePreload: {
      // 只保留明确需要提前加载的异步样式资源
      resolveDependencies: (url, deps, context) => {
        // hostType 可用于区分 HTML 入口和 JS chunk 的调用场景
        if (context.hostType === 'html') {
          return deps.filter((dep) => dep.endsWith('.css'))
        }

        // 其它场景保留默认候选，避免误删运行时依赖
        return deps
      }
    }
  }
})

这段代码展示的是配置边界，不是某个项目的固定答案。过滤条件必须建立在项目的产物命名和加载关系之上；如果把关键 JavaScript 依赖误删，页面可能在异步导航或组件首次打开时才暴露问题。

处理 base、非 HTML 入口和路径边界

Vite 文档说明，默认依赖路径会结合 base 生成。当 base 是相对值 '' 或 './' 时，运行时会使用 import.meta.url，避免把最终部署目录写死在绝对路径里。因此回调返回值不要直接拼接 CDN 域名，也不要返回脱离 build.outDir 的任意绝对路径。

非 HTML 自定义入口还要单独关注 polyfill 的导入位置：

// 自定义非 HTML 入口需要手动引入 modulepreload polyfill
import 'vite/modulepreload-polyfill'

// 继续加载应用自己的入口模块
import './app.js'

如果项目是 Library Mode，则应按库的消费者环境处理动态导入兼容，不要默认期待应用入口里的 polyfill 自动注入。这样可以避免把面向应用的加载假设带进可复用库。

按负载和约束选择配置

常见误区与落地清单

第一，不要把 polyfill: false 理解成“完全关闭 modulepreload”。它只关闭自动注入的 polyfill。第二，不要把 resolveDependencies 当成任意 URL 重写器，返回路径仍然受 build.outDir 约束。第三，回调是 experimental 能力，升级 Vite 时要重新阅读对应版本的 Build Options 文档。

落地时可以按下面顺序做决定：

// 先用默认行为，只有确有需求时再增加控制逻辑
const modulePreloadPolicy = {
  // 目标环境不需要兼容层时才关闭 polyfill
  polyfill: false,
  // 过滤逻辑应返回相对 build.outDir 的依赖路径
  resolveDependencies: (url, deps, context) => deps
}

export default {
  build: {
    modulePreload: modulePreloadPolicy
  }
}

如果没有可解释的过滤规则，就不要为了“看起来更可控”而添加回调。默认计算、明确的浏览器目标和清晰的产物目录，通常比一段难以维护的过滤逻辑更可靠。

相关问题

build.modulePreload 的默认值是什么？

文档给出的默认值是 { polyfill: true }。Vite 会自动注入 module preload polyfill，并计算动态导入所需的依赖。

resolveDependencies 能修改依赖路径吗？

可以返回经过过滤或调整的依赖数组，但返回路径应相对于 build.outDir。更进一步的路径处理还涉及其它构建配置，不应在回调里随意写入绝对线上地址。

关闭 polyfill 会不会停止预加载？

不会。它主要关闭 polyfill 注入；依赖列表的自动计算仍是另一层行为。