@plugin-light/project-config-uni-vite
Version:
开箱即用的项目配置，适用于 uni-app Vue3.x 项目
164 lines (107 loc) • 8.5 kB
Markdown
# 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/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-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 });
});
```
## 2. 参数
[完整类型定义](https://github.com/novlan1/plugin-light/blob/master/packages/project-config-uni-vite/src/types.ts)。
| 属性 | 类型 | 说明 | 默认值 |
| ------------------------- | ---------------------------------------------- | ------------------------------------------------------------ | ---------------------------- |
| 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` | uniTailwind 插件参数 | - |
| 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`，传递对象格式将作为插件参数 | - |
## 3. 常见问题
### 3.1. 支持的 `node.js` 版本
`node.js` 版本 >= 16
### 3.2. 环境变量如何注入
支持在环境变量文件中配置 `VUE_APP_DIR`，环境变量文件可以是 `.env`, `.env.local` 等，举例如下：
```bash
UNI_INPUT_DIR = './src/project/guandan-match'
VUE_APP_DIR = project/guandan-match
```
### 3.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')();
```
### 3.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` 问题，涉及到样式优先级问题，业务自己判断即可
### 3.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 下有效。
### 3.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` 产物。
### 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}/`
```
## 4. 更新日志
[点此查看](../changelog/project-config-uni-vite.md)