npm package: @plugin-light/project-config-vite
Description: 开箱即用的项目配置，适用于 Vue3.x 项目
Author: novlan1
Latest version: 1.0.9

# Vite 项目基础配置

<p align="center">
  <img src="https://img.shields.io/npm/dw/@plugin-light/project-config-vite">
  <img src="https://img.shields.io/npm/unpacked-size/@plugin-light/project-config-vite">
  <img src="https://img.shields.io/npm/v/@plugin-light/project-config-vite">
  <img src="https://img.shields.io/npm/l/@plugin-light/project-config-vite">
  <img src="https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white" alt="TypeScript strict">
  <img src="https://img.shields.io/badge/created-2022--01-blue?logo=github&logoColor=white">
</p>

封装 `vite.config.ts` 的基本配置，开箱即用。

## 1. 作者

**novlan1**

## 2. 如何使用

安装

```bash
pnpm add @plugin-light/project-config-vite -D
```

在 `vite.config.ts` 中添加如下设置：


```js
import { getViteBaseConfig } from "@plugin-light/project-config-vite";

import { defineConfig } from "vite";

export default defineConfig(({ mode }) => {
  return getViteBaseConfig({ mode });
});
```

## 3. 参数

[完整类型定义](https://github.com/novlan1/plugin-light/blob/master/packages/project-config-vite/src/types.ts)。

| 属性 | 类型 | <p style="width:300px">说明</p> | <p style="width:300px">默认值</p> |
| --- | --- | --- | --- |
| mode | `string` | 模式，对应 Vite 中 `defineConfig` 的 `mode` 参数 | - |
| serverPort | `number` | 本地开发端口（不传会取 `process.env.VUE_APP_PORT`，或 `443`） | - |
| serverHttps | `Server` | 本地开发是否是 `https` | - |
| serverHost | `string` \| `boolean` | 传给 `server.host`（参考 [Vite 文档](https://cn.vitejs.dev/config/server-options.html#server-host)） | - |
| optimizeDepsIncludes | `Array<string>` | 对应 `optimizeDeps.include` | - |
| optimizeDepsExcludes | `Array<string>` | 对应 `optimizeDeps.exclude` | - |
| addCodeAtEndOptions | `IAddCodeAtEndOptions` \| `boolean` | [add-code-at-end](./vite-plugin-add-code-at-end.html) 插件参数 | - |
| pressUiAlias | `string` | `press-ui` 本地的 `alias` 配置 | `src/library/press-ui` |
| pressPlusAlias | `string` | `press-plus` 本地的 `alias` 配置 | `src/library/press-plus` |
| aliasForLibraryOptions | `IAliasForLibraryOptions` | [alias-for-library](./vite-plugin-alias-for-library.html) 插件参数 | - |
| pmdAliasMap | `Record<string, string>` | `pmd-tools` 之类的别名映射 | - |
| customElements | `Array<string>` | 自定义元素配置 | - |
| useCdn | `boolean` | 三方库是否使用 `cdn` 链接（比如 `vue`，`vue-router`） | `false` |
| useElementPlusCDN | `boolean` | 是否使用 `element-plus` 的 `cdn` | `false` |
| mkcertOptions | `boolean` \| `MkcertPluginOptions` | [vite-plugin-mkcert](https://www.npmjs.com/package/vite-plugin-mkcert) 参数 | - |
| prePlugins | `Array<Plugin>` | 前置插件 | - |
| postPlugins | `Array<Plugin>` | 后置插件 | - |
| autoImportVant | `boolean` \| `VantResolverOptions` | 是否自动导入 `vant` | `true` |
| autoImportElementPlus | `boolean` \| `ElementPlusResolverOptions` | 是否自动导入 `element-plus` | `true` |
| autoImportTDesign | `boolean` \| `TDesignResolverOptions` | 是否自动导入 `tdesign` | `{ library: 'vue-next' }` |
| compressionOptions | `boolean` \| `ViteCompressionOptions` | `vite-plugin-compression` 插件参数 | true |
| legacyOptions | `boolean` \| `LegacyOptions` | `vitejs/plugin-legacy` 插件参数 | true |
| usePMDNetworkV2 | `boolean` | 是否使用 `pmd-network-v2` 替代 `pmd-network` | `false` |

## 4. 常见问题

### 4.1. 支持的 `node.js` 版本

`node.js` 版本 >= 16

### 4.2. 环境变量如何注入

支持在环境变量文件中配置 `VUE_APP_DIR`，环境变量文件可以是 `.env`, `.env.local` 等

也支持不配置，此时应用入口是 `src/main.ts`，即非 `monorepo` 模式

### 4.3. 如何进行打包产物分析

当 `process.env.VITE_VISUALIZER` 不为 `falsy` 时，本工具会使用 `rollup-plugin-visualizer` 插件，开发者可用来进行打包分析。

### 4.4. 如何兼容的 Vue 默认导出

内部使用了 [vite-plugin-export-default-in-vue](./vite-plugin-export-default-in-vue.html)，来兼容 `Vue2.x` 时期的默认导入 Vue 对象。

业务无感知，无影响。

### 4.5. optimizeDepsIncludes 含义是什么

对应 [optimizeDeps.include](https://vite.dev/config/dep-optimization-options.html#optimizedeps-include)，业务中常用到的有：

- md5
- js-cookie
- qs
- axios

### 4.6. Vite 升级之后可能会出现的问题

Vie 被曝出有[安全漏洞](https://github.com/vitejs/vite/security/advisories/GHSA-x574-m823-4x7w)，需升级到  `6.2.3+`。

升级之后可能对前端项目有几个影响。

1. `press-ui` 中某些变量无法识别

<img src="https://mike-1255355338.cos.ap-guangzhou.myqcloud.com/article/2025/4/own_mike_cf26d1ad18a538de18.png" width="800">

解决办法为，设置 `useCdn` 为 `false`。

```ts
getViteBaseConfig({
  useCdn: false,
})
```

2. `Promise.allSettled` 报错

这是因为 Vite 使用了较高级的语法，[某些低版本浏览器不支持](https://github.com/vitejs/vite/pull/19805)。

解决办法为，手动 `polyfill`。或升级 Vite 最新版本。

### 4.7. 业务中获取分支名等变量

流水线会注入以下环境变量：

```bash
# 分支
VITE_PUBLISH_BRANCH

# 发布人
VITE_PUBLISH_AUTHOR
```

业务可以参考下面的方式获取：

```ts
const CUR_BRANCH = (import.meta.env.VITE_PUBLISH_BRANCH || 'develop').replace(/\//, '.');

const shareUrl = `https://foo/bar.${CUR_BRANCH}/`
```

### 4.8. windows 编译慢的问题

可以给 `getViteBaseConfig` 传递以下参数，禁用掉一些三方库的 `alias` 逻辑。

```js
getViteBaseConfig({
  aliasForLibraryOptions: {},
  pressPlusAlias: '',
  pressUiAlias: '',
  pmdAliasMap: {},

  // 按需添加
  optimizeDepsIncludes: ['md5', 'js-cookie'],
})
```

注意：

- 需安装最新版本的 `press-ui`、`@plugin-light/project-config-vite` 等底层库
- [vite](https://github.com/vitejs/vite/blob/v6.3.1/packages/vite/CHANGELOG.md) 版本需 `>=6.3.1+`
- 三方库的 `javascript` 文件需自行处理条件编译等语法

效果对比，之前：

<img src="https://mike-1255355338.cos.ap-guangzhou.myqcloud.com/article/2025/4/own_mike_5cHAyptEeFXmTShB.png" width="800">

之后：

<img src="https://mike-1255355338.cos.ap-guangzhou.myqcloud.com/article/2025/4/own_mike_Tbtn6PNK7P5Gxse6.png" width="800">

原理：

Vite 最新版本会编译三方库的非 `javascript` 文件，所以不再需要 `alias` 逻辑，`javascript` 文件需自行处理。

### 4.9. 开发阶段报错503

本地开发时，如果遇到报错 503，如下图：

<img src="https://mike-1255355338.cos.ap-guangzhou.myqcloud.com/article/2025/7/own_mike_jYY2r6YZ4SaDFimY.png" width="600">

可以将 `mkcertOptions` 设为 `false`，即禁用掉 [vite-plugin-mkcert](https://www.npmjs.com/package/vite-plugin-mkcert) 插件。

```ts
getViteBaseConfig({
  mkcertOptions: false,
})
```

### 4.10. `console` 日志去除

生产环境默认会去掉 `console.log` 日志和 `debugger` 关键字。如果想更改默认行为，可以通过覆盖 `esbuild` 选项实现。

```ts
export default defineConfig(({ mode }) => {
  return {
    ...getViteBaseConfig({ mode }),
    // 覆盖 esbuild 配置即可
    esbuild: {},
  }
});
```

## 5. 更新日志

[点此查看](./CHANGELOG.md)