【Vite】配置文件 👌

在 Vite 中，配置文件项目根目录下的 vite.config.js 文件，最基本的格式为：

export default {
    // 配置选项
};

如果你的 Vite 配置文件不在项目根目录下，你也可以通过 –config 来进行指定：

vite --config my-config.js

Vite 提供了一个工具函数 defineConfig，通过它可以方便的获取类型提示，这对于使用 TS 编写配置尤其有用。

所以一般 Vite 配置文件的基本格式为：

export default defineConfig({
    // 配置选项
});

在 Vite 中，配置大致分为这么几类：

普通配置：设置项目的基本选项，别名、根目录、插件…
开发服务器配置：开发服务器的功能，开发服务器的端口、代理、CORS…
构建配置：构建生产版本时候的配置，输出目录、压缩、CSS 代码拆分…（TODO：链接文章）
预览配置：配置预览服务器的行为，端口、主机名…
依赖优化配置：针对依赖预构建做一些，比如可以新增包或者排除包
SSR 配置：服务器端渲染相关配置
Worker 配置：Web Worker 相关配置

这章主要介绍普通配置和开发服务器配置的常用选项。

普通配置

1. root

类型：string
默认值：process.cwd( ) ，默认就是项目根目录
描述：index.html 所在位置，可以是绝对路径，也可以是相对于当前工作目录的路径。

例如：

my-project/
├── public/
│   └── index.html
├── src/
│   ├── main.js
│   └── App.vue
└── vite.config.js

这个时候就可以使用 root 来进行配置：

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
    root: "public", // 将项目根目录设置为 'public' 文件夹
});

2. define

类型：Record<string, any>
描述：定义全局常量替换。在开发过程中，这些条目将被定义为全局变量，被定义为全局变量后，意味着不需要通过 import 来导入，直接使用；在构建过程中会被静态替换。
```
export default defineConfig({
    define: {
        __APP_VERSION__: JSON.stringify("v1.0.0"),
        __API_URL__: "window.__backend_api_url",
    },
});
```

注意：Vite 使用 esbuild 的 define 进行替换，因此值表达式必须是包含 JSON 可序列化的值（null、boolean、number、string、array、object）的字符串或单个标识符。对于非字符串值，Vite 会自动将其转换为 JSON 字符串。

JSON 可序列化指一个数据结构（如对象、数组等）能够被安全地转换为 JSON 格式字符串，且转换后的字符串可通过 JSON.parse() 完整还原为原始数据

3. resolve

resolve 对应的值是一个对象，对象里面对应了好几项配置。

3.1 alias

用于配置路径别名，这样可以简化模块路径引用。

// vite.config.js
import { defineConfig } from "vite";
import path from "path";

export default defineConfig({
    resolve: {
        alias: {
            // 将 '@' 指向 'src' 目录
            "@": path.resolve(__dirname, "src"),
            // 将 '@components' 指向 'src/components' 目录
            "@components": path.resolve(__dirname, "src/components"),
            // 将 '@utils' 指向 'src/utils' 目录
            "@utils": path.resolve(__dirname, "src/utils"),
        },
    },
});

之后在代码中就可以通过别名来指定目录：

// src/main.js
import { createApp } from "vue";
import App from "./App.vue";
import HelloWorld from "@components/HelloWorld.vue"; // 使用 '@components' alias
import { helperFunction } from "@utils/helpers"; // 使用 '@utils' alias

createApp(App).mount("#app");

3.2 extensions

在导入时省略文件扩展名时，尝试的文件扩展名列表。

注意，不推荐对自定义导入类型（如 .vue）省略扩展名，因为这可能会干扰 IDE 和类型支持。

默认值为 ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']

可以自定义扩展名的顺序，比如优先匹配 ts 类型：

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
    resolve: {
        extensions: [".ts", ".tsx", ".js", ".jsx", ".json"], // 自定义扩展名顺序
    },
});

4. CSS

CSS 配置项对应的值同样是一个对象，一个基本的格式如下：

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
    css: {
        // 其他配置项
    },
});

4.1 postcss

该配置项用于配置 PostCSS 的行为，可以是内联的 PostCSS 配置，也可以是自定义目录。

内联 PostCSS 配置：

// vite.config.js
import { defineConfig } from "vite";
import autoprefixer from "autoprefixer";
import cssnano from "cssnano";

export default defineConfig({
    css: {
        postcss: {
            // 在这里配置 postcss 相关内容，例如用哪个插件....
            plugins: [autoprefixer(), cssnano()],
        },
    },
});

自定义目录：

my-project/
├── config/
│   └── postcss.config.js
├── src/
│   └── main.js
└── vite.config.js

这个时候直接指定 postcss 的目录就可以了：

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
    css: {
        postcss: "config", // 指定自定义目录
    },
});

4.2 preprocessorOptions

该配置项用于为 CSS 预处理器指定配置，文件扩展名用于作为键来设置选项。每个预处理器支持的选项可以在它们各自的文档中找到：

CSS 预处理器是一种扩展 CSS 功能的工具，它允许开发者使用类编程语言的特性（变量、嵌套、函数等）编写样式代码，最终编译成标准的 CSS 文件。其核心目标是解决原生 CSS 在大型项目中难以维护的问题。

Sass/Scss 支持的配置选项
Less 支持的配置选项
styl/stylus - 目前仅支持 define，可以作为对象传递。

export default defineConfig({
    css: {
        // 配置 css 预处理器（一般情况下一个项目只用一个预处理器，这里只是演示）
        preprocessorOptions: {
            less: {
                math: "parens-division",
            },
            styl: {
                // 目前仅支持 define
                define: {
                    $specialColor: new stylus.nodes.RGBA(51, 197, 255, 1),
                },
            },
        },
    },
});

4.2.1 preprocessorOptions[extension].additionalData

当你想要为 CSS 预处理器（如 SCSS、SASS、Less 等）添加全局样式、变量、或混合器时，该选项非常有用。

import { defineConfig } from "vite";

export default defineConfig({
    css: {
        preprocessorOptions: {
            scss: {
                // 这里添加了一些全局变量，之后在任何的 Scss 文件中都可以使用这些全局变量
                additionalData: `$injectedColor: orange; $defaultMargin: 10px;`,
            },
        },
    },
});

import { defineConfig } from "vite";

export default defineConfig({
    css: {
        preprocessorOptions: {
            scss: {
                // 相当于给所有的 Scss 文件的头部都添加了这个引用，自动导入 mixins.scss 混合器文件
                additionalData: `@import "@/styles/mixins.scss";`,
            },
        },
    },
});

4.2.2 preprocessorMaxWorkers

如果启用了这个选项，那么 CSS 预处理器会尽可能在 worker 线程中运行。可以设置 number 值，也可以设置布尔值，例如设置成 true 的话表示 CPU 数量减 1.

4.3 devSourcemap

如果设置为 true，Vite 会生成 source map，并在浏览器中显示原始代码。

export default defineConfig({
    css: {
        // 开启 source maps
        devSourcemap: true,
    },
});

4.4 transformer

指定 CSS 处理的引擎，可以设置的值就两个，‘postcss’ 或者 ‘lightningcss’

lightingcss 就是 postcss 的 rust 版本。

服务器配置

服务器配置是指开发服务器，对应的配置项是 server

一个基本的格式如下：

export default defineConfig({
    server: {
        // 众多配置项
    },
});

下面是一些常见的配置项：

1. host

指定服务器应该监听哪个 IP 地址，默认是 localhost.

类型： string | boolean

默认： ‘localhost’

思考 🤔 正常情况下就是 localhost 就好了呀，什么情况下还存在要修改 host 的情况呢？

答案：除了 localhost 以外，我们经常还需要设置为 0.0.0.0 或者 true，表示监听所有的网络接口请求。有些时候需要多设备来测试应用。

2. port

监听的端口号，默认是 5173.

3. strictPort

如果设置为 true，Vite 将严格使用指定的端口。如果端口被占用，服务器启动将失败。

4. proxy

这个配置项非常常用，用于配置代理服务器。

export default defineConfig({
    server: {
        proxy: {
            "/foo": "http://localhost:4567", // 将 '/foo' 前缀的请求代理到 'http://localhost:4567'
        },
    },
});

对应的值也可以是对象的形式，对象形式能够包含更多的配置选项：

export default defineConfig({
    server: {
        proxy: {
            "/api": {
                target: "http://jsonplaceholder.typicode.com",
                changeOrigin: true,
                rewrite: (path) => path.replace(/^\/api/, ""), // 重写路径，将 '/api' 前缀去掉
            },
        },
    },
});

5. open

启动开发服务器时是否自动在浏览器中打开应用，默认值是 false.

6. https

是否启用 HTTPS。如果是一个对象，可以指定 SSL 证书和私钥的路径。

export default defineConfig({
    server: {
        https: {
            key: fs.readFileSync("/path/to/server.key"),
            cert: fs.readFileSync("/path/to/server.crt"),
        },
    },
});

7. watch

自定义文件监视器的选项。这对于开发过程中的**热模块替换（HMR）**非常关键。背后其实使用的是 chokidar（一个 Node.js 的文件系统监听库）它提供了多种可配置的监听选项。

import { defineConfig } from "vite";

export default defineConfig({
    server: {
        watch: {
            // 任何位于 ignored-directory 目录下的文件
            // 或者任何目录下面的 some-specific-file.txt 文件
            // 内容发生更改都不会触发 HMR
            ignored: ["**/ignored-directory/**", "**/some-specific-file.txt"],
        },
    },
});

watch 还支持更加细粒度的控制：

import { defineConfig } from "vite";

export default defineConfig({
    server: {
        watch: {
            ignored: "**/temp/**", // 忽略 temp 目录
            persistent: true, // 持续监听变化
            usePolling: true, // 使用轮询
            interval: 100, // 轮询间隔 100 毫秒
            binaryInterval: 300, // 对于二进制文件的轮询间隔
        },
    },
});

如果想要关闭文件监听，直接设置为 null 即可：

import { defineConfig } from "vite";

export default defineConfig({
    server: {
        watch: null,
    },
});

这里介绍的都是一些比较常用的配置项。至于其他的配置项，后面用到哪项再来具体介绍。