@plugin-light/project-config-vite/README.md

开箱即用的项目配置，适用于 Vue3.x 项目

## 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/github/last-commit/novlan1/plugin-light">
  <img src="https://img.shields.io/github/created-at/novlan1/plugin-light">
</p>

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

### 1. 如何使用

安装

```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 });
});
```

### 2. 参数

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

| 属性                   | 类型                                      | 说明                                                                                                 | 默认值                    |
| ---------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------- |
| 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` 插件参数                                                                           | -                         |
| pressUiAlias           | `string`                                  | `press-ui` 本地的 `alias` 配置                                                                       | `src/library/press-ui`    |
| pressPlusAlias         | `string`                                  | `press-plus` 本地的 `alias` 配置                                                                     | `src/library/press-plus`  |
| aliasForLibraryOptions | `IAliasForLibraryOptions`                 | `alias-for-library` 插件参数                                                                         | -                         |
| 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` 参数                                                                            | -                         |
| prePlugins             | `Array<Plugin>`                           | 前置插件                                                                                             | -                         |
| postPlugins            | `Array<Plugin>`                           | 后置插件                                                                                             | -                         |
| autoImportVant         | `boolean` \| `VantResolverOptions`        | 是否自动导入 `vant`                                                                                  | `true`                    |
| autoImportElementPlus  | `boolean` \| `ElementPlusResolverOptions` | 是否自动导入 `element-plus`                                                                          | `true`                    |
| autoImportTDesign      | `boolean` \| `TDesignResolverOptions`     | 是否自动导入 `tdesign`                                                                               | `{ library: 'vue-next' }` |

### 3. 常见问题

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

`node.js` 版本 >= 16

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

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

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

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

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

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

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

业务无感知，无影响。

#### 3.5. optimizeDepsIncludes 含义是什么

对应 `optimizeDeps.include`，业务中常用到的有：

- md5
- js-cookie
- qs
- axios

#### 3.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 最新版本。

#### 3.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}/`
```

#### 3.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. 更新日志

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