关于Vite的配置项及简单使用 - 麦兜家园

Vite 是一个超快速的前端构建工具，推动着下一代网络应用的发展。一个开发服务器，基于原生 ES模块提供了丰富的内建功能，如模块热更新（HMR）；一套构建指令，使用 Rollup 打包你的代码，并且它是预配置的，可以输出用于生产环境的优化过的静态资源。
Vite 还提供了强大的扩展性，可通过其插件 API 和 JavaScript API 进行扩展，并提供完整的类型支持。
当以命令行方式运行 vite 时，Vite 会自动解析项目根目录下名为 vite.config.js 的配置文件。

以下是vite常用的共享配置项说明：

root

类型： string

默认： process.cwd()

项目根目录（index.html 文件所在的位置）。可以是一个绝对路径，或者一个相对于该配置文件本身的相对路径。

base

类型： string

默认： /

开发或生产环境服务的公共基础路径。合法的值包括以下几种：

绝对 URL 路径名，例如 /foo/

完整的 URL，例如 https://bar.com/foo/ （域名部分在开发环境中不会被使用，因此该值与 /foo/ 相同）

空字符串或 ./（用于嵌入形式的开发）

mode

类型： string

默认： 'development' 用于开发，'production' 用于构建

在配置中指明将会把 serve 和 build 时的模式都覆盖掉。也可以通过命令行 --mode 选项来重写。

define

类型： Record<string, any>

定义全局常量替换方式。其中每项在开发环境下会被定义在全局，而在构建时被静态替换。

其值的表达式必须是一个包含 JSON 可序列化值（null、boolean、number、string、array 或 object）或单一标识符的字符串。对于非字符串值，Vite 将自动使用 JSON.stringify 将其转换为字符串。

plugins

类型： (Plugin | Plugin[] | Promise<Plugin | Plugin[]>)[]

需要用到的插件数组。Falsy 虚值的插件将被忽略，插件数组将被扁平化

publicDir

类型： string | false
默认： "public"

作为静态资源服务的文件夹。该目录中的文件在开发期间在 / 处提供，并在构建期间复制到 outDir 的根目录，并且始终按原样提供或复制而无需进行转换。该值可以是文件系统的绝对路径，也可以是相对于项目根目录的相对路径。

将 publicDir 设定为 false 可以关闭此项功能。

resolve.alias

类型：Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

将会被传递到 @rollup/plugin-alias 作为 entries 的选项。也可以是一个对象，或一个 { find, replacement, customResolver } 的数组。

当使用文件系统路径的别名时，请始终使用绝对路径。相对路径的别名值会原封不动地被使用，因此无法被正常解析。

resolve.extensions

类型： string[]
默认： ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']

导入时想要省略的扩展名列表。注意，不建议忽略自定义导入类型的扩展名（例如：.vue），因为它会影响 IDE 和类型支持。

css.modules

类型：

interface CSSModulesOptions {
  getJSON?: (
    cssFileName: string,
    json: Record<string, string>,
    outputFileName: string,
  ) => void
  scopeBehaviour?: 'global' | 'local'
  globalModulePaths?: RegExp[]
  exportGlobals?: boolean
  generateScopedName?:
    | string
    | ((name: string, filename: string, css: string) => string)
  hashPrefix?: string
  /**
   * 默认：undefined
   */
  localsConvention?:
    | 'camelCase'
    | 'camelCaseOnly'
    | 'dashes'
    | 'dashesOnly'
    | ((
        originalClassName: string,
        generatedClassName: string,
        inputFile: string,
      ) => string)
}

配置 CSS modules 的行为。选项将被传递给 postcss-modules。

当使用 Lightning CSS 时，该选项不会产生任何效果。如果要启用该选项，则应该使用 css.lightningcss.cssModules 来替代。

以下是服务器选项配置项：

server.host

类型： string | boolean
默认： 'localhost'

指定服务器应该监听哪个 IP 地址。如果将此设置为 0.0.0.0 或者 true 将监听所有地址，包括局域网和公网地址。

也可以通过 CLI 使用 --host 0.0.0.0 或 --host 来设置。

server.port

类型： number
默认值： 5173

指定开发服务器端口。注意：如果端口已经被使用，Vite 会自动尝试下一个可用的端口，所以这可能不是开发服务器最终监听的实际端口。

server.open

类型： boolean | string

开发服务器启动时，自动在浏览器中打开应用程序。当该值为字符串时，它将被用作 URL 的路径名。如果你想在你喜欢的某个浏览器打开该开发服务器，你可以设置环境变量 process.env.BROWSER （例如 firefox）。你还可以设置 process.env.BROWSER_ARGS 来传递额外的参数（例如 --incognito）。

server.proxy

类型： Record<string, string | ProxyOptions>

为开发服务器配置自定义代理规则。期望接收一个 { key: options } 对象。任何请求路径以 key 值开头的请求将被代理到对应的目标。如果 key 值以 ^ 开头，将被识别为 RegExp。configure 选项可用于访问 proxy 实例。如果请求匹配任何配置的代理规则，该请求将不会被 Vite 转换。

请注意，如果使用了非相对的基础路径 base，则必须在每个 key 值前加上该 base。

export default defineConfig({
  server: {
    proxy: {
      // 字符串简写写法：
      // http://localhost:5173/foo 
      // -> http://localhost:4567/foo
      '/foo': 'http://localhost:4567',
      // 带选项写法：
      // http://localhost:5173/api/bar 
      // -> http://jsonplaceholder.typicode.com/bar
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      // 正则表达式写法：
      // http://localhost:5173/fallback/ 
      // -> http://jsonplaceholder.typicode.com/
      '^/fallback/.*': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/fallback/, ''),
      },
      // 使用 proxy 实例
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        configure: (proxy, options) => {
          // proxy 是 'http-proxy' 的实例
        }
      },
      // 代理 websockets 或 socket.io 写法：
      // ws://localhost:5173/socket.io 
      // -> ws://localhost:5174/socket.io
      // 在使用 `rewriteWsOrigin` 时要特别谨慎，因为这可能会让
      // 代理服务器暴露在 CSRF 攻击之下
      '/socket.io': {
        target: 'ws://localhost:5174',
        ws: true,
        rewriteWsOrigin: true,
      },
    },
  },
})

server.hmr

类型： boolean | { protocol?: string, host?: string, port?: number, path?: string, timeout?: number, overlay?: boolean, clientPort?: number, server?: Server }

禁用或配置 HMR 连接（用于 HMR websocket 必须使用不同的 http 服务器地址的情况）。

设置 server.hmr.overlay 为 false 可以禁用开发服务器错误的屏蔽。

protocol 是用于设置 HMR 连接使用的 WebSocket 协议的选项，可以是 ws（WebSocket）或者 wss（WebSocket Secure）。

clientPort 是一个高级选项，只在客户端的情况下覆盖端口，这允许你为 websocket 提供不同的端口，而并非在客户端代码中查找。如果需要在 dev-server 情况下使用 SSL 代理，这非常有用。

当 server.hmr.server 被定义后，Vite 将会通过所提供的的服务器来处理 HMR 连接。如果不是在中间件模式下，Vite 将尝试通过已有服务器处理 HMR 连接。这在使用自签证书或想通过网络在某端口暴露 Vite 的情况下，非常有用。

server.origin

类型： string

用于定义开发调试阶段生成资源的 origin。

export default defineConfig({
  server: {
    origin: 'http://127.0.0.1:8080',
  },
})

以下是构建选项配置项：

build.target

类型： string | string[]
默认： 'baseline-widely-available'

最终软件包的浏览器兼容性目标。默认值是 Vite 的一个特殊值 'baseline-widely-available'，该值针对的是包含在 2026 年 1 月 1 日广泛可用的 Baseline 中的浏览器。具体来说，它是 ['chrome111', 'edge111', 'firefox114', 'safari16.4']。

另一个特殊值是 'esnext' —— 即假设有原生动态导入支持，并只执行最低限度的转译。

转换过程将会由 Oxc Transformer 执行，并且此值应该是一个合法的 Oxc Transformer 目标选项。自定义目标也可以是一个 ES 版本（例如：es2015）、一个浏览器版本（例如：chrome58）或是多个目标组成的一个数组。

build.modulePreload

类型： boolean | { polyfill?: boolean, resolveDependencies?: ResolveModulePreloadDependenciesFn }
默认值： { polyfill: true }

默认情况下，一个模块预加载 polyfill 会被自动注入。该 polyfill 会自动注入到每个 index.html 入口的的代理模块中。如果构建通过 build.rollupOptions.input 被配置为了使用非 HTML 入口的形式，那么必须要在你的自定义入口中手动引入该 polyfill：

import 'vite/modulepreload-polyfill'

注意：此 polyfill 不适用于 Library 模式。如果你需要支持不支持动态引入的浏览器，你应该避免在你的库中使用此选项。

此 polyfill 可以通过 { polyfill: false } 来禁用。

每个动态导入要预加载的块列表将由 Vite 计算。默认情况下，在载入这些依赖时，会使用一个包含 base 的绝对路径。如果 base 是相对路径（'' 或者 './'），解析时则会使用 import.meta.url，以避免出现依赖于最终部署基路径的绝对路径。

build.outDir

类型： string
默认： dist

指定输出路径（相对于项目根目录).

build.assetsDir

类型： string
默认： assets

指定生成静态资源的存放路径（相对于 build.outDir）。在库模式下不能使用。

build.cssCodeSplit

类型： boolean
默认： true

启用/禁用 CSS 代码拆分。当启用时，在异步 chunk 中导入的 CSS 将内联到异步 chunk 本身，并在其被加载时一并获取。

如果禁用，整个项目中的所有 CSS 将被提取到一个 CSS 文件中。

注意

如果指定了 build.lib，build.cssCodeSplit 会默认为 false。

build.cssTarget

类型： string | string[]
默认值：与 build.target 一致

此选项允许用户为 CSS 的压缩设置一个不同的浏览器 target，此处的 target 并非是用于 JavaScript 转写目标。

build.sourcemap

类型： boolean | 'inline' | 'hidden'
默认： false

构建后是否生成 source map 文件。如果为 true，将会创建一个独立的 source map 文件。如果为 'inline'，source map 将作为一个 data URI 附加在输出文件中。'hidden' 的工作原理与 true 相似，只是 bundle 文件中相应的注释将不被保留。

build.rolldownOptions

类型： RolldownOptions

自定义底层的 Rolldown 打包配置。这与从 Rolldown 配置文件导出的选项相同，并将与 Vite 的内部 Rolldown 选项合并。

以下是依赖优化项配置项：　

optimizeDeps.entries

类型： string | string[]

默认情况下，Vite 会抓取你的 index.html 来检测需要预构建的依赖项（忽略了node_modules、build.outDir、__tests__ 和 coverage）。如果指定了 build.rollupOptions.input，Vite 将转而去抓取这些入口点。

如果这两者都不合你意，则可以使用此选项指定自定义条目——该值需要遵循 tinyglobby 模式，或者是相对于 Vite 项目根目录的匹配模式数组。当显式声明了 optimizeDeps.entries 时默认只有 node_modules 和 build.outDir 文件夹会被忽略。如果还需忽略其他文件夹，你可以在模式列表中使用以 ! 为前缀的、用来匹配忽略项的模式。对于明确包含字符串 node_modules 的模式，不会忽略 node_modules。

optimizeDeps.exclude

类型： string[]

在预构建中强制排除的依赖项。

CommonJS

CommonJS 的依赖不应该排除在优化外。如果一个 ESM 依赖被排除在优化外，但是却有一个嵌套的 CommonJS 依赖，则应该为该 CommonJS 依赖添加 optimizeDeps.include。例如：

export default
defineConfig
({
optimizeDeps
: {
include
: ['esm-dep > cjs-dep'],
  },
})

optimizeDeps.include

类型： string[]

默认情况下，不在 node_modules 中的，链接的包不会被预构建。使用此选项可强制预构建链接的包。

实验性：如果你使用的是一个有很多深层导入的库，你也可以指定一个尾部的 glob 模式来一次性地预构建所有深层导入。这将避免在使用新的深层导入时不断地预构建。可以在此提供反馈。例如：

export default

({

: {

: ['my-lib/components/**/*.vue'],
  },
})

optimizeDeps.rolldownOptions

类型： Omit<``RolldownOptions, 'input' | 'logLevel' | 'output'> & { output?: [Omit](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)<RolldownOutputOptions, 'format' | 'sourcemap' | 'dir' | 'banner'>}`

在依赖扫描和优化过程中传递给 Rolldown 的选项。

某些选项进行了省略，因为修改它们与 Vite 的优化方案并不兼容。

plugins 与 Vite 的 dep 插件合并

optimizeDeps.esbuildOptions

类型： Omit<EsbuildBuildOptions, | 'bundle' | 'entryPoints' | 'external' | 'write' | 'watch' | 'outdir' | 'outfile' | 'outbase' | 'outExtension' | 'metafile'>
已弃用

此选项在内部被转换为 optimizeDeps.rolldownOptions。请使用 optimizeDeps.rolldownOptions 代替。

optimizeDeps.force

类型： boolean

设置为 true 可以强制依赖预构建，而忽略之前已经缓存过的、已经优化过的依赖。

optimizeDeps.noDiscovery

类型： boolean
默认： false

设置为 true 时，自动依赖项发现将被禁用，并且仅优化 optimizeDeps.include 中列出的依赖项。在开发过程中，仅 CJS 依赖项必须存在于 optimizeDeps.include 中。

optimizeDeps.holdUntilCrawlEnd

实验性：提供反馈
类型： boolean
默认： true

当该功能被启用时，系统会在冷启动时保持第一个优化的依赖结果，直到所有的静态导入都被检索完毕。这样可以避免因为发现新的依赖项而触发新的公共 chunk 生成，从而需要刷新整个页面。如果通过扫描和在 include 中明确定义的方式能找到所有的依赖项，那么最好关闭这个功能，这样浏览器可以并行处理更多的请求。

optimizeDeps.disabled

已废弃
实验性：提供反馈
类型： boolean | 'build' | 'dev'
默认： 'build'

此选项已被弃用。从 Vite 5.1 版本开始，构建过程中对依赖项的预打包已经被移除。将 optimizeDeps.disabled 设置为 true 或 'dev' 将会禁用优化器，配置为 false 或 'build' 将会在开发模式下启用优化器。

如果你想完全禁用优化器，可以设置 optimizeDeps.noDiscovery: true 来禁止自动发现依赖项，并保持 optimizeDeps.include 未定义或为空。

WARNING

在构建过程中优化依赖项是一个实验性的功能。尝试这种策略的项目也会使用 build.commonjsOptions: { include: [] } 来移除 @rollup/plugin-commonjs。如果你这样做，将会有一个警告提示你在打包时需要重新启用它，以支持仅使用 CJS 的包。

optimizeDeps.needsInterop

实验性
类型: string[]

当导入这些依赖项时，会强制 ESM 转换。Vite 能够正确检测到依赖项是否需要转换处理（interop），因此通常不需要使用此选项。然而，不同的依赖项组合可能导致其中一些包以不同方式预构建。将这些包添加到 needsInterop 中可以通过避免重新加载整个页面来加快冷启动速度。如果某个依赖项符合此情况，Vite 将抛出警告，建议你在配置中添加该包名。

以上是常用的配置项，接下来简单创建一个vite项目来简单认识下vite吧：

Vite 提供了多种方式来创建新项目，最简单的方式是使用命令行工具。

打开终端或命令行工具，运行以下命令来创建一个新的 Vite 项目：