这是 Vite 1.x – 6.x 旧版文档归档 / This is Vite 1.x – 6.x legacy archive

• 本文档对应插件版本：vite-plugin-view ≤ 4.x、vite-plugin-external ≤ 7.x、vite-plugin-build-chunk ≤ 4.x 等旧发行版。
• 适用打包器：Rollup / esbuild（Vite 6 及之前的默认组合）。不支持 Vite 8+ 的 Rolldown 打包器，Vite 7/8+ 用户请立即返回新文档。
• 本目录内容已冻结，不再维护。遇到新功能/新字段请查看最新文档：
  • 中文新文档：/zh/plugins/
  • English new docs：/plugins/

配置选项参考（旧版）

Type definitions copied verbatim from the plugin TypeScript source:

/**
 * Reverse-lookup function for the global name of an external id.
 *
 * Typically the resolveHook built by setExternals — returns
 *   - string  → named external (e.g. 'react' → 'React')
 *   - true    → pure external (no global name)
 *   - false   → not external
 *
 * The 2nd/3rd args are optional so a single-arg `(id) => ...` resolver
 * (used by handleGlobals' default branch, which only needs the id) is
 * assignable to this type.
 *
 * 反查 external id → 全局变量名的函数。通常是 setExternals 构建的
 * resolveHook——返回 string 表示命名 external（react → React）；
 * 返回 true 表示纯 external；false 表示不是 external。
 * 2/3 参数可选，让 handleGlobals 默认分支里只用 id 的单参 resolver
 * 也能赋值给本类型。
 */
export type GlobalNameResolver = (
  id: string,
  importer?: string | undefined,
  isResolved?: boolean,
) => string | boolean | null | undefined | void;

/**
 * Return value helpers shared across the plugin decision-making pipeline.
 * Defined locally because Vite 8 dropped the direct rollup peer dep.
 *
 * 决策管线中所有返回值类型。本地定义是因为 Vite 8 不再直接依赖 rollup，
 * 我们也不想从 rolldown 里引这些底层类型。
 */
export type NullValue = null | undefined | void;

/**
 * The single signature that every "external decision" hook inside this plugin
 * compiles down to (see ExternalHook).
 *
 * 设计背景（Design rationale）：
 * 用户能用非常多的形态声明 externals（Record、function、string、RegExp、数组、
 * true …）。为了让 dev/build/pre-bundle 三处入口共享一套判断逻辑，我们把所有
 * 输入形态都"编译"为同签名函数（详见 ExternalHook）。后续主流程不再关心
 * 原始形态。
 *
 * All user-facing external shapes are normalised to this single signature so
 * every entry point (dev resolveId, build resolveId, DepsOptimizer
 * pre-bundling) shares the exact same decision logic — no divergence.
 *
 * 返回值语义（Return values）：
 *   - true  → import is external, **without** a global-name/URL mapping.
 *            Used by externalizeDeps and string/RegExp matches.
 *            标记为 external，但不提供替换规则（只不打包）。用于 externalizeDeps。
 *   - string → if an absolute URL → ESM CDN route; otherwise → IIFE global
 *             route (see makeCjsExternalCode / makeEsExternalCode).
 *             绝对 URL → ES CDN 重导出；否则 → IIFE 全局变量（写 CJS shim）。
 *   - falsy → not external; proceed to the next hook / normal resolution.
 *            不是 external，继续正常解析。
 */
export type ExternalFn = (
  source: string,
  importer: string | undefined,
  isResolved: boolean,
) => string | boolean | NullValue;

export type ModuleNameFn = ((id: string) => string);

/**
 * Globals resolver accepted by Rolldown output.globals (either static map
 * or a function deriving the name at runtime).
 *
 * Rolldown output.globals 接受的形态：对象是静态字典，函数是动态反查。
 */
export type ModuleNameMap = Record<string, string> | ModuleNameFn;

/**
 * Options that are valid for both the root Options and any per-mode
 * override (opts.development / opts.production).
 *
 * 设计背景（Design rationale）：
 * 多环境配置场景：开发环境 react → React（unpkg 的 umd），生产环境 react
 * → $linkdesign.React（自有 CDN）。为了让用户只覆盖 externals/cacheDir 等
 * 业务字段，不覆盖 enforce/enableBanner 这种插件级字段，将选项拆成两个接口。
 *
 * We split "field overrides per mode" from "global plugin options" so users
 * can write "development: { externals: {...} }" without accidentally
 * overriding enforce, enableBanner, or the build-time helpers.
 */
export interface BasicOptions {
  /**
   * External dependencies. 配置外部依赖。
   *
   * Five accepted shapes（五种输入形态）：
   *   1. Record<string, string>  —— {react:React} 或 {react:https://esm.sh/...}
   *   2. ExternalFn             —— (src, imp, resolved) => string|true|false
   *   3. string / RegExp        —— single match rule, hit → pure external
   *                                单条匹配规则，命中即 external（不给全局名）
   *   4. Array<string|RegExp>   —— multiple match rules
   *   5. true                   —— externalise *every* import (rare)
   *                                所有 import 都 external（极少用）
   */
  externals?:
    | ExternalFn
    | boolean
    | string
    | RegExp
    | Array<string | RegExp>
    | Record<string, string>;

  /** Log level. 输出日志等级。 */
  logLevel?: LogLevel;

  /**
   * CWD used when turning a relative cacheDir path absolute.
   * Defaults to process.cwd().
   *
   * 当前工作目录，用于把相对的 cacheDir 拼成绝对路径。
   * 默认 process.cwd()。
   */
  cwd?: string;

  /**
   * Folder for stash files. See ExternalIIFE / ExternalES for why a
   * real on-disk file is required per named external.
   * Defaults to ${cwd}/node_modules/.vite_external (kept next to Vite
   * own .vite cache for easy "rm -rf node_modules/.vite*" cleanup).
   *
   * stash 文件存放目录。每个"命名 external"（Record 形式）都会在里面写一个
   * JS shim。默认 ${cwd}/node_modules/.vite_external，紧邻 Vite 自带的
   * .vite 缓存，方便 rm -rf node_modules/.vite* 一键清理。
   */
  cacheDir?: string;
}

/**
 * Full user-facing options shape.
 *
 * Notes：
 *   - The [mode: string] index signature accepts development /
 *     production / any custom mode as a BasicOptions override.
 *     索引签名允许 opts.development / opts.production 等特定模式字段
 *     （BasicOptions 覆盖）。
 *   - rollback 是历史遗留字段，Vite 8 合并为单一实现后已无实现。
 *     保留是因为公共配置发布过，用户可能仍写在 vite.config 里，空值不影响运行。
 *   - externalGlobals is the escape-hatch plugin for fixing Rolldown/Rollup
 *     Issue #3188 (IIFE top-level require not rewritten to a global).
 */
export interface Options {
  /**
   * External dependencies for specific mode
   * (e.g. development: { externals: { react: React } })
   *
   * 针对指定模式覆盖 BasicOptions 字段（例如开发模式用 unpkg 全局、生产模式用
   * 自有 CDN 全局变量前缀）。
   */
  [mode: string]: BasicOptions | any;

  /**
   * @deprecated No-op since the Vite 8 unification. Kept purely for
   * backward-compat with old vite.config files that still set it.
   *
   * 已废弃：Vite 8 版本将两套实现（alias + depsOptimizer）合并为单一的
   * DepsOptimizer + resolveId 路线，不再有"回退"分支。保留字段空壳只为兼容
   * 历史上写了 rollback: true 的 vite.config。
   */
  rollback?: boolean;

  /**
   * Interop escape hatch — preserved behaviour from pre-Vite-8 versions.
   *
   * 历史行为：当设置 interop: auto 时，build 阶段会**清空**
   * build.rolldownOptions.external，强制所有 external 通过 stash 文件路径
   * 走 resolveId 解析（而不是 Rolldown 原生 external 机制）。
   *
   * Historical behaviour preserved intact: if interop is auto the build
   * step clears build.rolldownOptions.external, forcing every external
   * to resolve through the stash-file path instead of Rolldown native
   * external flag.
   *
   * Why this exists：
   * 原场景是 IIFE 构建时某些库被 output.globals 处理后仍生成错误的 require
   * 包装。解决方法是"构建阶段也当成 shim 打包"，让 Rolldown 把它当作普通依赖
   * bundle 进去，shim 只有一行 module.exports = React; Rolldown 的 IIFE
   * 包装就能正确处理。
   *
   * The original IIFE scenario: for some libraries, marking them as
   * external + relying on output.globals still wrapped the top-level
   * require incorrectly. Using stash files instead makes Rolldown treat
   * the lib as a normal in-bundle dependency, and the 1-line CJS shim
   * (module.exports = React;) is a shape that Rolldown IIFE output has
   * always been able to wrap correctly.
   */
  interop?: 'auto';

  /**
   * Plugin enforce. External-related resolveId/load MUST run before generic
   * plugins — otherwise @vitejs/plugin-react or similar may resolve
   * react to node_modules/react before we get a chance to redirect it.
   * external.ts therefore defaults to enforce: pre. Users can still
   * override to post for edge cases.
   *
   * Vite 插件 enforce。external 的 resolveId/load 必须在普通插件之前执行，
   * 否则其他插件（比如 @vitejs/plugin-react）可能会先把 react 解析到
   * node_modules/react，本插件就没有机会重定向了。因此 external.ts 默认
   * enforce: pre，用户仍可显式改成 post 用于特殊场景。
   */
  enforce?: 'pre' | 'post';

  /**
   * Shortcut: also treat Node built-ins (fs, path, node:stream/*…)
   * as external during command === build. No-op in dev because Node
   * built-ins never resolve in-browser anyway.
   *
   * 快捷开关：把所有 Node.js 内置模块（fs、path、node:stream 等）也作为
   * external。只在 build 阶段生效（dev 阶段浏览器里 Node 内置模块本来就不会
   * 被 resolve，没必要多此一举）。
   */
  nodeBuiltins?: boolean;

  /**
   * Shortcut: treat these libraries (strings or regexes) as pure externals
   * — they are not bundled, but no global-name / CDN shim is provided for
   * them. Only active during command === build.
   *
   * 快捷开关：这些依赖（字符串或正则）一律不打包进产物。不提供全局名 / CDN shim，
   * 等价于对每个 dep 调用 externalHook.use 匹配命中即 true。只在 build 阶段生效。
   */
  externalizeDeps?: Array<string | RegExp>;

  /**
   * Fixes https://github.com/rollup/rollup/issues/3188
   *
   * Receives a resolver (id) => string | undefined that answers the same
   * question as Rolldown output.globals (lookup via the compiled
   * externals hooks above), and must return a Rolldown-compatible plugin
   * that rewrites top-level imports/requires to their equivalent global
   * accesses (window.React / globalThis.React).
   *
   * Typical usage: wrap @rolldown/plugin-external-globals (or its Rollup
   * ancestor). The produced plugin is prepended to rolldownOptions.plugins
   * so its transforms run **before** Rolldown own globals handling.
   *
   * 逃生舱：修复 Rolldown/Rollup Issue #3188（IIFE 输出时顶层 require/import
   * 没能被正确替换成 window.xxx 访问）。回调参数 globals(id) 可直接反查
   * 本插件 externals 的结果，等价于 Rolldown 原生 output.globals。返回值是
   * Rolldown 插件，会被放在 rolldownOptions.plugins 数组的**最前面**，这样
   * 它的 transform 先于 Rolldown 内置 globals 处理运行。
   */
  externalGlobals?: (globals: ModuleNameMap) => Rolldown.Plugin;

  /** Whether to print the plugin banner on startup. 启动时是否输出 banner 行。 */
  enableBanner?: boolean;
}

/**
 * Post-processed options carried through every downstream step.
 *
 * Produced by buildOptions() which: merges per-mode overrides, defaults
 * cwd/cacheDir, sets logger level, and spreads ConfigEnv (mode, command,
 * ssrBuild…) onto the result so downstream code never has to carry two
 * parameters around.
 *
 * 内部"最终版选项"形态。由 buildOptions() 生成：合并模式 override、补齐
 * cwd/cacheDir 默认值、设置日志级别、再把 ConfigEnv（mode、command 等）扩展
 * 字段一起挂上去。这样下游判断"现在是 build 还是 serve"不用再单独传 ConfigEnv。
 */
export interface ResolvedOptions {
  cwd: string;
  cacheDir: string;
}

externals

• 类型：ExternalFn | boolean | string | RegExp | Array<string | RegExp> | Record<string, string>
• 必填：false

配置外部依赖项。示例

logLevel

• 类型："TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL" | "OFF"
• 必填：false
• 默认值："WARN"

设置日志级别。

nodeBuiltins

• 类型：boolean
• 必填：false

是否排除 Node.js 内置模块。示例

externalizeDeps

• 类型：Array<string | RegExp>
• 必填：false

指定需要排除的打包依赖项。示例

externalGlobals

• 类型：(globals: Record<string, any>) => rollup.Plugin
• 必填：false

解决 IIFE 打包问题（Rollup Issue #3188）。示例

rollback

• 类型：boolean
• 必填：false

是否回退到旧版实现。

interop

• 类型："auto" | undefined
• 必填：false

控制 Vite 的默认构建策略调整。示例

enforce

• 类型：'pre' | 'post'
• 必填：false

设置插件执行顺序。可选值：pre（前置）或 post（后置）。参考 Vite 插件顺序。

cwd

• 类型：string
• 必填：false
• 默认值：process.cwd()

设置解析 cacheDir 相对路径时的当前工作目录。

cacheDir

• 类型：string
• 必填：false
• 默认值：${cwd}/node_modules/.vite_external

缓存目录路径。

[mode: string]

• 类型：BasicOptions
• 必填：false

为特定模式配置外部依赖项。示例

---

TypeScript 类型定义

import type { NullValue, Plugin as RollupPlugin } from 'rollup';
import type { ConfigEnv } from 'vite';
import type { LogLevel } from 'vp-runtime-helper';

export type ExternalFn = (
  source: string,
  importer: string | undefined,
  isResolved: boolean
) => string | boolean | NullValue;

export type ModuleNameMap = Record<string, string> | ((id: string) => string);

export type { LogLevel } from 'vp-runtime-helper';

export interface BasicOptions {
  /**
   * 解析 `cacheDir` 路径时的当前工作目录。
   * @default `process.cwd()`
   */
  cwd?: string;

  /**
   * 缓存目录路径
   * @default `${cwd}/node_modules/.vite_external`
   */
  cacheDir?: string;

  /**
   * 外部依赖项配置
   */
  externals?:
    | ExternalFn
    | boolean
    | string
    | RegExp
    | Array<string | RegExp>
    | Record<string, string>;

  /**
   * 日志级别配置
   */
  logLevel?: LogLevel;
}

export interface Options extends BasicOptions {
  /**
   * 按模式配置的外部依赖项
   */
  [mode: string]: BasicOptions | any;

  /**
   * 回退到旧版实现
   */
  rollback?: boolean;

  /**
   * 控制 Vite 的默认行为
   */
  interop?: 'auto';

  /**
   * 插件执行顺序（"pre" 或 "post"）
   */
  enforce?: 'pre' | 'post';

  /**
   * 是否排除 Node.js 内置模块
   */
  nodeBuiltins?: boolean;

  /**
   * 需要排除的打包依赖项
   */
  externalizeDeps?: Array<string | RegExp>;

  /**
   * 解决 Rollup#3188 问题（https://github.com/rollup/rollup/issues/3188）
   */
  externalGlobals?: (globals: ModuleNameMap) => RollupPlugin;
}

export interface ResolvedOptions extends Options, ConfigEnv {
  cwd: string;
  cacheDir: string;
}