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

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

# Uni App Vite 项目基础配置

<p align="center">
  <img src="https://img.shields.io/npm/dw/@plugin-light/project-config-uni-vite">
  <img src="https://img.shields.io/npm/unpacked-size/@plugin-light/project-config-uni-vite">
  <img src="https://img.shields.io/npm/v/@plugin-light/project-config-uni-vite">
  <img src="https://img.shields.io/npm/l/@plugin-light/project-config-uni-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-uni-vite -D
```

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


```js
import { getUniVue3ViteConfig } from '@plugin-light/project-config-uni-vite';

import { defineConfig } from 'vite';

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

## 3. 参数

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

| 属性 | 类型 |  <p style="width:300px">说明</p>  |  <p style="width:300px">默认值</p>  |
| --- | --- | --- | --- |
| mode | `string` | 模式 | - |
| uni | `any` | `uni` 插件 | - |
| port | `CommonServerOptions['port']` | 端口，传递给 `server.port` | `443` |
| https | `Server` | `https` 配置，传递给 `server.https` | - |
| host | `CommonServerOptions['host']` | `host` 配置，传递给 `server.host` | `true` |
| prePlugins | `Array<Plugin>` | 前置插件 | - |
| postPlugins | `Array<Plugin>` | 后置插件 | - |
| optimizeDepsIncludes | `Array<string>` | 对应 `optimizeDeps.include` | - |
| removeVueDirectionOptions | `IRemoveVueDirectionOptions` | [remove-vue-direction](./vite-plugin-remove-vue-directive.html) 插件参数 | - |
| hmr | `ServerOptions['hmr']` | `hmr` 选项 | `{ timeout: 1000 * 60 * 5 }` |
| warnList | `ICrossGameStyleOptions['warnList']` | 语法警报列表，比如 `v-model`，`destroyed` | - |
| transformWebTagOptions | `boolean \| TransformWebTagOptions` | [transform-web-tag](./postcss-plugin-transform-web-tag.html) `postcss` 插件参数 | - |
| removeSelectorOptions | `boolean \| RemoveSelectorOptions` | [remove-selector](./postcss-plugin-remove-selector.html) `postcss` 插件参数 | - |
| uniTailwindOptions | `boolean \| UniTailwindPluginUserOptions` | [uni-tailwind](https://www.npmjs.com/package/@uni-helper/vite-plugin-uni-tailwind) 插件参数 | - |
| tailwindcssOptions | `boolean \| Parameters<typeof tailwindcss>[0]` | [tailwindcss](https://www.npmjs.com/package/tailwindcss) `postcss` 插件参数 | - |
| buildOptions | `BuildOptions` | 构建选项 | - |
| useChunkSplit | `boolean` | 是否使用 [chunk-split](./vite-plugin-chunk-split.html) | `false` |
| useLegacy | `boolean \| LegacyOptions` | 是否使用 [@vitejs/plugin-legacy](https://www.npmjs.com/package/@vitejs/plugin-legacy)，传递对象格式将作为插件参数 | `false` |
| uniOptions | `any` | 传递给 [uni](https://www.npmjs.com/package/@dcloudio/vite-plugin-uni) 插件的参数 | - |
| useESBuildPlugin | `boolean \| ESBuildOptions` | 是否使用 [rollup-plugin-esbuild](https://www.npmjs.com/package/rollup-plugin-esbuild)，传递对象格式将作为插件参数 | - |
| usePMDNetworkV2 | `boolean` | 是否使用 `pmd-network-v2` 替代 `pmd-network` | `false` |
| usePolling | `boolean` | 是否使用文件轮询监听（`usePolling`），轮询比原生 `fs.watch` 慢且 CPU 占用高，仅在 Docker/WSL 等不支持 inotify 的环境下需要开启 | `true` |
| useVisualizer | `boolean` | 是否开启 `visualizer` 产物分析插件，设为 `false` 可跳过 gzip/brotli 计算，加快构建速度 | `true` |
| useNodeResolve | `boolean` | 是否使用 `@rollup/plugin-node-resolve`，Vite 内部已有 resolve 能力，关闭可减少重复解析开销 | `true` |
| buildTarget | `string` | 构建目标，传递给 `build.target`（仅 H5 生效）。不需要兼容旧浏览器时可设为 `es2020` 或 `esnext` 以减少 polyfill，加快构建 | `'es2015'` |

## 4. 常见问题

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

`node.js` 版本 >= 16

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

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

```bash
UNI_INPUT_DIR = './src/project/guandan-match'
VUE_APP_DIR = project/guandan-match
```

### 4.3. 对外脚本怎么用

本插件导出了几个脚本，外部可以使用。

1. 修复 `uni-app` 中 `monorepo` 仓库下打包路径问题

原理是修改了 `node_modules/@dcloudio/uni-cli-shared/dist/utils.js` 源码中的 `normalizeNodeModules` 方法，增加了下面这句：

```ts
str = str.replace(/^[./]*/, '');
```

使用方式：

```ts
require('@plugin-light/project-config-uni-vite/public-script/uni/fix-uni-dir');
```

2. 修复 `uni-app` 小程序下样式文件变化无法重新编译的问题


小程序开发时，独立的 `sass` 文件改动后并不会重新编译，用一个全新的示例工程也不可以。看了下源码，`uni-app` 是用 `import('vite').then({build}=>{})` 这种方式来启动的。

解决办法是利用 `gulp.watch`，监听 `./src/**/*.scss` 文件，然后修改下 `main.ts`，然后这样就能重新编译了。同时加上了 `debounce`。

使用方式：

```ts
require('@plugin-light/project-config-uni-vite/public-script/watch/watch-sass')();
```

### 4.4. SCSS 警告说明是怎么做的

配置中屏蔽了 [import](https://sass-lang.com/documentation/breaking-changes/import/)、[legacy-js-api](https://sass-lang.com/documentation/breaking-changes/legacy-js-api/)、[mixed-decls](https://sass-lang.com/documentation/breaking-changes/mixed-decls/) 的相关警告信息。

原因如下：

1. `uni-app` 会把 `uni.scss` 放到业务每个 `scss` 前面，所以 `@import` 改成 `@use` 后，会报错 `@use rules must be written before any other rules`

2. `legacy-js-api` 问题，也是 `uni-app` 中使用了 `node-sass` 的 `renderSync`

3. `mixed-decls` 问题，涉及到样式优先级问题，业务自己判断即可

### 4.5. useChunkSplit 含义是什么

设置 `useChunkSplit` 为 `true` 后，将会开启：

1. 将 `aegis-v2`、`axios` 作为外链
2. 将一些库单独拆包
   - `t-comm、press-ui、press-plus、 pmd-npm` => `pmd-pkg`
   - `@dcloudio/uni-h5` => `uni-h5`

仅在 H5 下有效。

### 4.6. 低版本浏览器兼容是怎么做的

使用方式为，设置 `useLegacy` 为 `true`。

原理，使用了 [@vitejs/plugin-legacy](https://www.npmjs.com/package/@vitejs/plugin-legacy) 这个三方库，以及[修复了它不支持 `CDN` 的问题](./vite-plugin-legacy-polyfill.html)。

是否会影响 H5 在高版本浏览器的性能？基本不会，具体可自行搜索 [@vitejs/plugin-legacy](https://www.npmjs.com/package/@vitejs/plugin-legacy) 的原理。

如何判断当前项目是运行的的 `module` 产物，还是 `legacy` 产物？控制台打印 `window.__vite_is_modern_browser`，为 `true` 则表示运行的是 `module` 产物，否则为 `legacy` 产物。

### 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. 监听样式文件变动

UI开发某些情况会遇到下面的问题：样式文件改动，但需重新编译才能生效。这里其实是 `uni-app` 自己的问题。

解决办法如下：

1. `packages.json` 修改或添加下面的 `script`

```json
{
  "dev": "concurrently \"npm run watch:sass\" \"npm run dev:h5\"",
  "dev:mp": "concurrently \"npm run watch:sass\" \"npm run dev:mp-weixin\"",
  "watch:sass": "node script/watch-sass"
}
```

2. 增加监听脚本

```js
// script/watch-sass.js

require('@plugin-light/project-config-uni-vite/public-script/watch/watch-sass')();
```

### 4.9. HMR 失效处理方案

如果使用 `whistle` 代理时，造成 HMR 失效，解决方案如下。

在 `whistle` 中增加对 `websocket` 的代理。

```bash
# 之前配置，代理 443 端口
127.0.0.1:443  https://h5-test.igame.qq.com

# 新增配置，代理 websocket
wss://h5-test.igame.qq.com wss://127.0.0.1:443 
```

HMR 成功示例如下：

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

HRM 失败示例如下：

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

另外，成功后通过浏览器“网络”面板也能看到对应的 `websocket` 链接。

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

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

注意，发现 `src/local-component/xx` 组件 以下面方式引入 `scss` 时，HMR 正常：

```scss
<style lang="scss" scoped>
@import './scss/index.scss';
</style>
```

下面形式不可以

```scss
<style lang="scss" src="./scss/index.scss" scoped></style>
```

推测是 `vite` 或其依赖模块内部问题。

解决方案，参考 [监听样式文件变动](#_4-8-监听样式文件变动)。

## 5. 更新日志

[点此查看](../changelog/project-config-uni-vite.md)