Uni App Vite 项目基础配置

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

1. 作者

novlan1

2. 如何使用

安装

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	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 插件参数	-
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，传递对象格式将作为插件参数	-

4. 常见问题

4.1. 支持的 node.js 版本

node.js 版本 >= 16

4.2. 环境变量如何注入

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

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 方法，增加了下面这句：

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

使用方式：

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。

使用方式：

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

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

配置中屏蔽了 import、legacy-js-api、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 这个三方库，以及修复了它不支持 CDN 的问题。

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

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

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

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

# 分支
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 自己的问题。

解决办法如下：

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

{
  "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. 增加监听脚本

// script/watch-sass.js

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

4.9. HMR 失效处理方案

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

在 whistle 中增加对 websocket 的代理。

# 之前配置，代理 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 正常：

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

下面形式不可以

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

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

解决方案，参考 监听样式文件变动。

5. 更新日志

点此查看