进阶配置

Vite 进阶：server.proxy、resolve.alias、SSR、多页面、库模式、vite preview 等。环境变量见 env。

一、环境变量

1. `import.meta.env` 及其类型扩展

Vite 使用 import.meta.env 暴露环境变量，默认包含：

import.meta.env.MODE：当前模式（如 development、production）
import.meta.env.BASE_URL：应用部署的基础路径
import.meta.env.PROD：是否为生产环境
import.meta.env.DEV：是否为开发环境
import.meta.env.SSR：是否为服务端渲染环境

类型扩展：在 src/vite-env.d.ts 或 env.d.ts 中添加类型声明，获得 TypeScript 提示。

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE: string;
  readonly VITE_APP_TITLE: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

2. `.env.[mode]` 文件的加载优先级

Vite 根据当前模式加载对应的环境文件，优先级从低到高：

.env（所有环境通用）
.env.local（被 git 忽略）
.env.[mode]（如 .env.development、.env.production）
.env.[mode].local

后面的文件会覆盖前面的同名变量。

3. 自定义前缀（`envPrefix`）

默认只有以 VITE_ 开头的变量才会暴露给客户端。可以通过 envPrefix 修改前缀，支持字符串或数组。

// vite.config.js
export default {
  envPrefix: ["VITE_", "CUSTOM_"],
};

4. 在生产构建中静态替换（`define` 选项）

构建时，import.meta.env.VITE_* 会被静态替换为实际值。对于自定义全局常量，也可以使用 define 进行硬替换。

export default {
  define: {
    __APP_VERSION__: JSON.stringify("1.0.0"),
    "process.env.NODE_ENV": '"production"',
  },
};

二、代理配置进阶

1. `server.proxy` 基本配置

基于 http-proxy，支持路径重写、修改 Cookie 域、自定义响应头。

export default {
  server: {
    proxy: {
      "/api": {
        target: "http://localhost:3000",
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ""),
        cookieDomainRewrite: "", // 清除 cookie domain
        headers: { "X-Custom": "value" }, // 添加请求头
      },
    },
  },
};

2. 多个代理规则的顺序与优先级

规则按顺序匹配，第一个匹配的规则生效。可以使用 ^/api/ 等更具体的路径提高优先级。

proxy: {
  '^/api/users': { target: 'http://user-service:3000' },
  '/api': { target: 'http://default-service:3000' },
}

3. 绕过代理（`bypass` 函数）

根据请求条件动态决定是否代理。

proxy: {
  '/api': {
    target: 'http://localhost:3000',
    bypass(req, res, proxyOptions) {
      if (req.headers.accept?.includes('html')) {
        return '/index.html';   // 不代理，返回本地文件
      }
    },
  },
},

三、路径别名

1. `resolve.alias` 配置

支持对象形式或 { find, replacement } 数组形式（用于更灵活的匹配）。

export default {
  resolve: {
    alias: {
      "@": "/src",
      "~": path.resolve(__dirname, "./src"),
    },
  },
};

2. 注意别名冲突与 IDE 配置同步（`tsconfig.json` 的 `paths`）

在 TypeScript 项目中，需要同步 tsconfig.json 的 paths 选项，保证 IDE 类型解析和 Vite 一致。

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "~/*": ["src/*"]
    }
  }
}

对于 JS 项目，可添加 jsconfig.json。

四、服务端渲染（SSR）支持

1. `vite build --ssr` 构建服务端入口

使用 vite build --ssr src/entry-server.js 构建服务端 bundle（输出 CommonJS 或 ESM 格式）。

// vite.config.js
export default {
  build: {
    ssr: true, // 或在命令行指定
    rollupOptions: {
      input: "src/entry-server.js",
      output: { format: "cjs" },
    },
  },
};

2. `ssrLoadModule` 运行时加载模块

在开发模式下，可以使用 ssrLoadModule 加载服务端模块，进行实时编译。

// server.js
const { createServer } = require("vite");

(async () => {
  const vite = await createServer();
  const entry = await vite.ssrLoadModule("/src/entry-server.js");
  const html = await entry.render();
  console.log(html);
})();

3. SSR 环境下的模块加载策略（`ssr.noExternal`、`ssr.external`）

ssr.external：将依赖标记为外部，不打包进服务端 bundle（适合 Node 原生模块）。
ssr.noExternal：强制将依赖打包（适合需要转译的依赖，如 CSS-in-JS）。

export default {
  ssr: {
    external: ["vue", "axios"],
    noExternal: ["@my/ui-library"],
  },
};

4. 条件导入（`import.meta.env.SSR`）

在代码中可以根据环境进行条件导入，避免在客户端引入 Node 模块。

if (import.meta.env.SSR) {
  const fs = await import("fs");
  // 服务端逻辑
} else {
  // 客户端逻辑
}

五、多页面应用配置

1. `build.rollupOptions.input` 配置多个 HTML 入口

import { resolve } from "path";

export default {
  build: {
    rollupOptions: {
      input: {
        main: resolve(__dirname, "index.html"),
        about: resolve(__dirname, "about.html"),
        contact: resolve(__dirname, "contact.html"),
      },
    },
  },
};

每个 HTML 文件都会作为单独入口，Vite 会分析其引用的脚本和样式，生成对应的 chunk。

2. 为每个页面单独生成对应的 chunk

默认每个页面会生成独立 JS 和 CSS 文件。可以通过 manualChunks 进一步细化分割，例如将公共库提取到 vendor，每个页面共享。

build: {
  rollupOptions: {
    output: {
      manualChunks(id) {
        if (id.includes('node_modules')) return 'vendor';
      },
    },
  },
},

六、库模式

1. `build.lib` 配置打包库

export default {
  build: {
    lib: {
      entry: "src/index.js",
      name: "MyLibrary", // 全局变量名（用于 UMD）
      formats: ["es", "umd"], // 输出格式
      fileName: (format) => `my-lib.${format}.js`,
    },
    rollupOptions: {
      external: ["vue"], // 排除依赖，不打包进库
      output: {
        globals: { vue: "Vue" },
      },
    },
  },
};

2. 输出 es、umd 等格式，并处理 external 依赖

es 格式适合现代打包工具（Tree Shaking 友好）。
umd 格式适合直接 <script> 引入。
external 告诉 Rollup 不要打包指定依赖，由使用方提供。

七、预览服务器优化

`vite preview` 的生产环境预览

构建完成后，使用 vite preview 可以启动一个本地静态服务器，模拟生产环境。常用选项：

bash

vite preview --port 5000 --host 0.0.0.0 --cors

也可以在配置文件中预设：

export default {
  preview: {
    port: 5000,
    host: "0.0.0.0",
    cors: true,
    strictPort: true, // 端口被占用时直接退出
  },
};

预览服务器会使用 dist 目录的内容，可以用于测试构建产物的行为，不支持热更新。

总结

配置类别	关键 API / 特性
环境变量	`import.meta.env`，`.env.[mode]` 优先级，`envPrefix`，`define`
代理	`server.proxy`，路径重写、`bypass` 函数、多规则顺序
路径别名	`resolve.alias`，配合 `tsconfig.json` 的 `paths`
SSR	`build --ssr`，`ssrLoadModule`，`ssr.noExternal`，条件导入
多页面	`build.rollupOptions.input` 多入口
库模式	`build.lib`，输出 es/umd，external + globals
预览服务器	`vite preview`，`preview` 配置项

熟练使用这些高级配置，可以应对绝大多数前端工程的定制需求。

参考文献

以下链接在编写时均可正常访问：

资料	说明
配置参考	官方
SSR	服务端渲染
库模式	build.lib