Uni App Vite 项目基础配置

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

1. 作者

novlan1

2. 如何使用

安装

bash

pnpm add @plugin-light/project-config-uni-vite -D

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

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

import { defineConfig } from 'vite';

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

3. 参数

完整类型定义。

属性	类型	说明	默认值
mode	`string`	模式	-
uni	`any`	`uni` 插件	-
port	`CommonServerOptions['port']`	端口，传递给 `server.port`。⚠️ `uni-app` 项目下不生效，端口由 `manifest.json` 的 `h5.devServer.port` 决定，详见常见问题 4.10	`443`
https	`Server`	`https` 配置，传递给 `server.https`。⚠️ `uni-app` 项目下同样由 `manifest.json` 的 `h5.devServer.https` 决定	-
host	`CommonServerOptions['host']`	`host` 配置，传递给 `server.host`	`true`
useMkcert	`boolean \| IMkcertOptions`	是否启用 vite-plugin-mkcert，为本地 dev server 生成受系统信任的 HTTPS 证书，仅 H5 下生效。使用 `whistle` 等代理中转 HTTPS 请求到本地时强烈推荐开启，详见常见问题 4.11	`true`
prePlugins	`Array<Plugin>`	前置插件	-
postPlugins	`Array<Plugin>`	后置插件	-
optimizeDepsIncludes	`Array<string>`	对应 `optimizeDeps.include`	-
removeVueDirectionOptions	`IRemoveVueDirectionOptions`	remove-vue-direction 插件参数	-
hmr	`ServerOptions['hmr']`	`hmr` 选项	`{ timeout: 1000 * 60 * 5 }`
warnList	`ICrossGameStyleOptions['warnList']`	语法警报列表，比如 `v-model`，`destroyed`	-
transformWebTagOptions	`boolean \| TransformWebTagOptions`	transform-web-tag `postcss` 插件参数	-
removeSelectorOptions	`boolean \| RemoveSelectorOptions`	remove-selector `postcss` 插件参数	-
uniTailwindOptions	`boolean \| UniTailwindPluginUserOptions`	uni-tailwind 插件参数	-
tailwindcssOptions	`boolean \| Parameters<typeof tailwindcss>[0]`	tailwindcss `postcss` 插件参数	-
buildOptions	`BuildOptions`	构建选项	-
useChunkSplit	`boolean`	是否使用 chunk-split	`false`
useLegacy	`boolean \| LegacyOptions`	是否使用 @vitejs/plugin-legacy，传递对象格式将作为插件参数	`false`
uniOptions	`any`	传递给 uni 插件的参数	-
useESBuildPlugin	`boolean \| ESBuildOptions`	是否使用 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. 对外脚本怎么用

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

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

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

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

使用方式：

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

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

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

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

使用方式：

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

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

配置中屏蔽了 import、legacy-js-api、mixed-decls 的相关警告信息。

原因如下：

uni-app 会把 uni.scss 放到业务每个 scss 前面，所以 @import 改成 @use 后，会报错 @use rules must be written before any other rules
legacy-js-api 问题，也是 uni-app 中使用了 node-sass 的 renderSync
mixed-decls 问题，涉及到样式优先级问题，业务自己判断即可

4.5. useChunkSplit 含义是什么

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

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

仅在 H5 下有效。

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

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

原理，使用了 @vitejs/plugin-legacy 这个三方库，以及修复了它不支持 CDN 的问题。

是否会影响 H5 在高版本浏览器的性能？基本不会，具体可自行搜索 @vitejs/plugin-legacy 的原理。

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

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

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

bash

# 分支
VITE_PUBLISH_BRANCH

# 发布人
VITE_PUBLISH_AUTHOR

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

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

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

4.8. 监听样式文件变动

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

解决办法如下：

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"
}

增加监听脚本

// 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 成功示例如下：

HRM 失败示例如下：

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

注意，发现 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.10. 如何修改 dev server 端口

先说结论：vite.config.ts 里传 port 或修改 server.port 都不会生效，必须改项目的 manifest.json。

4.10.1. 原因

uni-app 强行覆盖了 Vite 的 server 配置，链路如下：

@dcloudio/uni-h5-vite 插件的 createConfig 通过 Vite plugin config 钩子注入 server 配置
server 内容来自 manifest.json 的 h5.devServer 字段
关键在合并逻辑（@dcloudio/uni-h5-vite/dist/plugin/config.js:52-63）：只允许用户的 vite.config.ts.server 覆盖 host / fs / watch 三个字段，其他字段（port / https / proxy / disableHostCheck 等）一律以 manifest.json 为准

也就是说 vite.config.ts 里的 server.port = 8443 会被 manifest.json 里的 h5.devServer.port = 443 覆盖，最终 dev server 还是跑在 443。

4.10.2. 正确改法

修改项目下 manifest.json 的 h5.devServer：

json

{
  "h5": {
    "devServer": {
      "port": 8443,
      "https": true,
      "disableHostCheck": true
    }
  }
}

保存后重启 dev 脚本即可。

4.10.3. 常见配合场景

配合 whistle 代理时，规则里的端口要与 manifest.json 保持一致：

bash

# manifest.json 里 h5.devServer.port 改为 8443 后，whistle 规则同步改
127.0.0.1:8443  https://h5-test.igame.qq.com

4.11. useMkcert 何时需要开启

推荐场景：使用 whistle 等代理把 HTTPS 请求（如 https://h5-test.igame.qq.com/）中转到本地 dev server 时，需要开启。

4.11.1. 原因

whistle 会用自己的 CA 对外承担 TLS，然后以 HTTP 或 HTTPS 方式回源到本地 dev server
本插件默认使用 @vitejs/plugin-basic-ssl 生成的临时自签名证书。这类证书不受系统信任、每次启动随机变化、Node.js TLS 握手容易不稳定，导致 socket hang up 等错误
vite-plugin-mkcert 会生成一个受 macOS/Windows 系统信任的 root CA + localhost 证书（存在 ~/.vite-plugin-mkcert/），首次启动会弹出系统密码框做授权

4.11.2. 使用方式

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

export default defineConfig(({ mode }) => {
  return getUniVue3ViteConfig({
    mode,
    uni,
    useMkcert: true,          // 使用默认 { source: 'coding' }（内网友好）
    // useMkcert: { source: 'coding', hosts: ['localhost', 'my-dev.local'] },
  });
});

4.11.3. 首次启动步骤

pnpm dev:h5 启动后，vite-plugin-mkcert 会：
- 从 source: 'coding' 镜像下载 mkcert 二进制
- 生成 root CA 并调用系统钥匙串将其标为"始终信任"（首次会弹密码框）
- 签发 localhost / 127.0.0.1 证书给 Vite dev server 使用
之后 whistle 中转 HTTPS 请求到本地时 TLS 握手正常，浏览器打开代理域名也不再有证书警告

4.11.4. 如何验证是否生效

bash

# 命令行验证 —— 证书链应该显示 mkcert 的 root CA
openssl s_client -connect localhost:443 -showcerts < /dev/null | grep Issuer

浏览器打开 https://localhost:{port}/ 应该看到"连接是安全的"，没有证书警告。

5. 更新日志

点此查看

Uni App Vite 项目基础配置 ​

1. 作者 ​

2. 如何使用 ​

3. 参数 ​

4. 常见问题 ​

4.1. 支持的 node.js 版本 ​

4.2. 环境变量如何注入 ​

4.3. 对外脚本怎么用 ​

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

4.5. useChunkSplit 含义是什么 ​

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

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

4.8. 监听样式文件变动 ​

4.9. HMR 失效处理方案 ​

4.10. 如何修改 dev server 端口 ​

4.10.1. 原因 ​

4.10.2. 正确改法 ​

4.10.3. 常见配合场景 ​

4.11. useMkcert 何时需要开启 ​

4.11.1. 原因 ​

4.11.2. 使用方式 ​

4.11.3. 首次启动步骤 ​

4.11.4. 如何验证是否生效 ​

5. 更新日志 ​

Uni App Vite 项目基础配置

1. 作者

2. 如何使用

3. 参数

4. 常见问题

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

4.2. 环境变量如何注入

4.3. 对外脚本怎么用

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

4.5. useChunkSplit 含义是什么

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

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

4.8. 监听样式文件变动

4.9. HMR 失效处理方案

4.10. 如何修改 dev server 端口

4.10.1. 原因

4.10.2. 正确改法

4.10.3. 常见配合场景

4.11. useMkcert 何时需要开启

4.11.1. 原因

4.11.2. 使用方式

4.11.3. 首次启动步骤

4.11.4. 如何验证是否生效

5. 更新日志