Vite核心配置vite.config.js全选项解析与说明-开发者社区-阿里云

Vite 官方文档速通（上）https://developer.aliyun.com/article/1512020?spm=a2c6h.13148508.setting.30.f8774f0euyBLtl

二. 配置

1. 配置 Vite

运行 vite 时会自动解析项目根目录下名为 vite.config.js 的配置文件。可以通过 --config 命令行选项指定一个配置文件：

vite --config my-config.js

1.1 情景配置

如果配置文件需要基于（dev/serve 或 build）命令或者不同的模式来决定选项：

// 开发参数：{ development, serve, false, false }
export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  // "serve" 开发环境，"build" 生产环境
  if (command === "serve") {
    return {
      // dev 独有配置
    };
  } else {
    // command === 'build'
    return {
      // build 独有配置
    };
  }
});

1.2 在配置中使用环境变量

Vite 默认是不加载环境变量，可以通过 loadEnv 函数来加载指定的 .env 文件：

import { defineConfig, loadEnv } from "vite";
 
export default defineConfig(({ command, mode }) => {
  // 根据当前工作目录中的 `mode` 加载 .env 文件
  // 设置第三个参数为 '' 来加载所有环境变量，而不管是否有 `VITE_` 前缀。
  const env = loadEnv(mode, process.cwd(), "");
  return {
    // vite 配置
    define: {
      __APP_ENV__: JSON.stringify(env.APP_ENV),
    },
  };
});

2. 共享选项

2.1 root

类型：string，默认：process.cwd()

打包入口 index.html 文件位置。默认在上项目根目录（index.html 文件所在的位置）。

2.2 base

类型：string，默认：/

开发或生产环境服务的公共基础路径。

2.3 mode

类型：string，默认：'development' 开发，'production' 构建

配置后会将 serve 和 build 时的模式都覆盖掉。

2.4 define

类型：Record

定义全局常量替换方式。

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify("v1.0.0"),
    __API_URL__: "window.__backend_api_url",
  },
});

2.5 plugins

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

需要用到的插件数组。

2.6 publicDir

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

作为静态资源服务的文件夹。

2.7 cacheDir

类型：string，默认："node_modules/.vite"

存储缓存文件的目录。

2.8 resolve.alias

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

当使用文件系统路径的别名时，请始终使用绝对路径。

2.9 resolve.dedupe

类型：string[]

强制 Vite 始终将列出的依赖项解析为同一副本

2.10 resolve.conditions

类型：string[]

解决程序包中情景导出时的其他允许条件。

{
  "exports": {
    ".": {
      "import": "./index.esm.js",
      "require": "./index.cjs.js"
    }
  }
}

2.11 resolve.mainFields

类型：string[]，默认：['browser', 'module', 'jsnext:main', 'jsnext']

package.json 中，在解析包的入口点时尝试的字段列表。

2.12 resolve.extensions

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

导入时想要省略的扩展名列表。

2.13 resolve.preserveSymlinks

类型：Boolean，默认：false

启用此选项会使 Vite 通过原始文件路径（即不跟随符号链接的路径）而不是真正的文件路径（即跟随符号链接后的路径）确定文件身份。

2.14 css.modules

配置 CSS modules 的行为。

2.15 css.postcss

类型：string | (postcss.ProcessOptions & { plugins?: postcss.AcceptedPlugin[] })

内联的 PostCSS 配置

2.16 css.preprocessorOptions

类型：Record

指定传递给 CSS 预处理器的选项。

2.17 css.devSourcemap

类型：boolean，默认：false

在开发过程中是否启用 sourcemap。

2.18 css.transformer

类型：'postcss' | 'lightningcss'，默认：'postcss'

2.19 css.lightningcss

该选项用于配置 Lightning CSS。

2.20 json.namedExports

类型：boolean，默认：true

是否支持从 .json 文件中进行按名导入。

2.21 json.stringify

类型：boolean，默认：false

若设置为 true，导入的 JSON 会被转换为 export default JSON.parse("...")，这样会比转译成对象字面量性能更好，尤其是当 JSON 文件较大的时候。

2.22 esbuild

类型：ESBuildOptions | false

ESBuildOptions 继承自 esbuild 转换选项。

export default defineConfig({
  esbuild: {
    jsxFactory: "h",
    jsxFragment: "Fragment",
  },
});

2.23 assetsInclude

类型：string | RegExp | (string | RegExp)[]

指定额外的 picomatch 模式作为静态资源处理。

export default defineConfig({
  assetsInclude: ["**/*.gltf"],
});

2.24 logLevel

类型：'info' | 'warn' | 'error' | 'silent'

调整控制台输出的级别，默认为 'info'。

2.25 customLogger

类型：使用自定义 logger 记录消息。

2.26 clearScreen

类型：boolean，默认：true

设为 false 可以避免 Vite 清屏而错过在终端中打印某些关键信息。

2.27 envDir

类型：string，默认：root

用于加载 .env 文件的目录。

2.28 envPrefix

类型：string | string[]，默认：VITE\_

以 envPrefix 开头的环境变量会通过 import.meta.env 暴露在你的客户端源码中。

2.29 appType

类型：'spa' | 'mpa' | 'custom'，默认：'spa'

3. 服务器选择

3.1 server.host

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

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

3.2 server.port

类型：number，默认：5173

指定开发服务器端口。

3.3 server.strictPort

类型：boolean

设为 true 时若端口已被占用则会直接退出，而不是尝试下一个可用端口。

3.4 server.https

类型：https.ServerOptions

启用 TLS + HTTP/2。当 server.proxy 选项也被使用时，将会仅使用 TLS。

3.5 server.open

类型：boolean | string

开发服务器启动时，自动在浏览器中打开应用程序。

3.6 server.proxy

类型：Record

为开发服务器配置自定义代理规则。changeOrigin：true 时浏览器会将请求设置为 targte 的值。

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
      "/socket.io": {
        target: "ws://localhost:5174",
        ws: true,
      },
    },
  },
});

3.8 server.headers

类型：OutgoingHttpHeaders

指定服务器响应的 header。

3.9 server.hmr

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

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

3.10 server.warmup

类型：{ clientFiles?: string[], ssrFiles?: string[] }

提前转换和缓存文件以进行预热。

export default defineConfig({
  server: {
    warmup: {
      clientFiles: ["./src/components/*.vue", "./src/utils/big-utils.js"],
      ssrFiles: ["./src/server/modules/*.js"],
    },
  },
});

3.11 server.watch

类型：object | null

传递给 chokidar 的文件系统监听器选项。

3.12 server.middlewareMode

类型：'ssr' | 'html'，默认：false

以中间件模式创建 Vite 服务器。

3.13 server.fs.strict

类型：boolean，默认：true

限制为工作区 root 路径以外的文件的访问。

3.14 server.fs.allow

类型：string[]

限制哪些文件可以通过 /@fs/ 路径提供服务。

3.15 server.fs.deny

类型：string[]，默认：['.env', '.env.*', '*.{crt,pem}']

3.16 server.origin

类型：string

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

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

3.17 server.sourcemapIgnoreList

类型：false | (sourcePath: string, sourcemapPath: string) => boolean，默认：(sourcePath) => sourcePath.includes('node_modules')

是否忽略服务器 sourcemap 中的源文件，用于填充 x_google_ignoreList source map 扩展。

export default defineConfig({
  server: {
    // 这是默认值，它将把所有路径中含有 node_modules 的文件
    // 添加到忽略列表中。
    sourcemapIgnoreList(sourcePath, sourcemapPath) {
      return sourcePath.includes('node_modules')
    }
  }
};

4. 构建选择

4.1 build.target

类型：string | string[]，默认：'modules'

设置最终构建的浏览器兼容目标。

4.2 build.modulePreload

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

默认情况下，一个模块预加载 polyfill 会被自动注入。

4.3 build.outDir

类型：string，默认：dist

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

4.4 build.assetsDir

类型：string，默认：assets

指定生成静态资源的存放路径（相对于 build.outDir）。

4.5 build.assetsInlineLimit

类型：number，默认：4096

小于此阈值的导入或引用资源将内联为 base64 编码，以避免额外的 http 请求。

4.6 build.cssCodeSplit

类型：boolean，默认：true

启用/禁用 CSS 代码拆分。

4.7 build.cssTarget

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

此选项允许用户为 CSS 的压缩设置一个不同的浏览器 target。

4.8 build.cssMinify

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

允许用户覆盖 CSS 最小化压缩的配置

4.9 build.sourcemap

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

构建后是否生成 source map 文件。

4.10 build.rollupOptions

类型：RollupOptions

自定义底层的 Rollup 打包配置。

4.11 build.commonjsOptions

类型：RollupCommonJSOptions

传递给 @rollup/plugin-commonjs 插件的选项。

4.12 build.dynamicImportVarsOptions

类型：RollupDynamicImportVarsOptions

传递给 @rollup/plugin-dynamic-import-vars 的选项。

4.13 build.lib

类型：{ entry: string | string[] | { [entryAlias: string]: string }, name?: string, formats?: ('es' | 'cjs' | 'umd' | 'iife')[], fileName?: string | ((format: ModuleFormat, entryName: string) => string) }

构建为库。

4.14 build.manifest

类型：boolean | string，默认：false

可以为一些服务器框架渲染时提供正确的资源引入链接。

4.15 build.ssrManifest

类型：boolean | string，默认值： false

为 true 时，构建也将生成 SSR 的 manifest 文件。

4.16 build.ssr

类型：boolean | string，默认值： false

生成面向 SSR 的构建。

4.17 build.ssrEmitAssets

类型：boolean，默认：false

4.18 build.minify

类型：boolean | 'terser' | 'esbuild'，默认：'esbuild'

用来指定使用哪种混淆器。

4.19 build.terserOptions

类型：TerserOptions

指定最大的工作线程数。

4.20 build.write

类型：boolean，默认：true

设置为 false 来禁用将构建后的文件写入磁盘。

4.21 build.emptyOutDir

类型：boolean，默认：若 outDir 在 root 目录下，则为 true

构建时清空该目录。

4.22 build.copyPublicDir

类型：boolean，默认：true

默认情况下，Vite 会在构建阶段将 publicDir 目录中的所有文件复制到 outDir 目录中。可以通过设置该选项为 false 来禁用该行为。

4.23 build.reportCompressedSize

类型：boolean，默认：true

启用/禁用 gzip 压缩大小报告。

4.23 build.chunkSizeWarningLimit

类型：number，默认：500

规定触发警告的 chunk 大小（以 kB 为单位）。

4.24 build.watch

类型：WatcherOptions| null，默认：null

设置为 {} 则会启用 rollup 的监听器。

5. 预览选择

5.1 preview.host

类型：string | boolean，默认：server.host

为开发服务器指定 ip 地址。

5.2 preview.port

类型：number，默认：4173

指定开发服务器端口。

5.3 preview.strictPort

类型：boolean，默认：server.strictPort

设置为 true 时，如果端口已被使用，则直接退出

5.4 preview.https

类型：boolean | https.ServerOptions，默认：server.https

启用 TLS + HTTP/2。

5.5 preview.open

类型：boolean | string，默认：server.open

开发服务器启动时，自动在浏览器中打开应用程序。

5.6 preview.proxy

类型：Record，默认：server.proxy

配置自定义代理规则。

5.7 preview.cors

类型：boolean | CorsOptions，默认：server.cors

配置 CORS。

5.8 preview.headers

类型：OutgoingHttpHeaders

指明服务器返回的响应头。

6. 依赖优化选择

6.1 optimizeDeps.entries

类型： string | string[]

默认情况下，Vite 会抓取你的 index.html 来检测需要预构建的依赖项。

6.2 optimizeDeps.exclude

类型： string[]

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

6.3 optimizeDeps.include

类型： string[]

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

6.4 optimizeDeps.esbuildOptions

类型： EsbuildBuildOptions

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

6.5 optimizeDeps.force

类型： boolean

设置为 true 可以强制依赖预构建。

6.6 optimizeDeps.disabled

类型： boolean | 'build' | 'dev'，默认： 'build'

禁用依赖优化，值为 true 将在构建和开发期间均禁用优化器。

6.7 optimizeDeps.needsInterop

类型: string[]

当导入这些依赖项时，会强制 ESM 转换。

三. vite.config.ts 常用基础配置

import { defineConfig, loadEnv } from "vite";
import vue from "@vitejs/plugin-vue";
import { resolve } from "path";
 
// https://vitejs.dev/config/
export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  const env = loadEnv(mode, process.cwd(), "");
 
  if (command == "serve") {
    // 'server' 开发环境
    console.log("开发");
  } else {
    // 'build' 生产环境
    console.log("生产");
  }
 
  return {
    base: "/",
    envPrefix: "YQ",
    plugins: [vue()],
    resolve: {
      alias: {
        "@": resolve(__dirname, "./src"),
      },
    },
    server: {
      host: "127.0.0.1",
      port: 8080,
      strictPort: true,
      open: true,
      proxy: {
        "/foo": "http://localhost:1111",
        "/api": {
          target: "http://localhost:1112",
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, ""),
        },
      },
    },
    build: {
      outDir: "dist",
      assetsDir: "assets",
      cssCodeSplit: true,
      emptyOutDir: true,
    },
  };
});

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

Vite 官方文档速通（下）

二. 配置

1. 配置 Vite

1.1 情景配置

1.2 在配置中使用环境变量

2. 共享选项

2.1 root

2.2 base

2.3 mode

2.4 define

2.5 plugins

2.6 publicDir

2.7 cacheDir

2.8 resolve.alias

2.9 resolve.dedupe

2.10 resolve.conditions

2.11 resolve.mainFields

2.12 resolve.extensions

2.13 resolve.preserveSymlinks

2.14 css.modules

2.15 css.postcss

2.16 css.preprocessorOptions

2.17 css.devSourcemap

2.18 css.transformer

2.19 css.lightningcss

2.20 json.namedExports

2.21 json.stringify

2.22 esbuild

2.23 assetsInclude

2.24 logLevel

2.25 customLogger

2.26 clearScreen

2.27 envDir

2.28 envPrefix

2.29 appType

3. 服务器选择

3.1 server.host

3.2 server.port

3.3 server.strictPort

3.4 server.https

3.5 server.open

3.6 server.proxy

3.8 server.headers

3.9 server.hmr

3.10 server.warmup

3.11 server.watch

3.12 server.middlewareMode

3.13 server.fs.strict

3.14 server.fs.allow

3.15 server.fs.deny

3.16 server.origin

3.17 server.sourcemapIgnoreList

4. 构建选择

4.1 build.target

4.2 build.modulePreload

4.3 build.outDir

4.4 build.assetsDir

4.5 build.assetsInlineLimit

4.6 build.cssCodeSplit

4.7 build.cssTarget

4.8 build.cssMinify

4.9 build.sourcemap

4.10 build.rollupOptions

4.11 build.commonjsOptions