董海洋
239 lines
14 KiB
Markdown
239 lines
14 KiB
Markdown
# 模板说明
|
||
|
||
## 包管理工具
|
||
|
||
`pnpm@10+`
|
||
|
||
## 脚本命令
|
||
|
||
| 命令 | 说明 |
|
||
| ---------- | ---------------------------------------------- |
|
||
| prepare | husky钩子，安装依赖时会自动执行husky的准备工作 |
|
||
| dev | 开发指令，环境：dev |
|
||
| dev:qa | 开发指令，环境：qa |
|
||
| dev:pre | 开发指令，环境：pre |
|
||
| dev:prod | 开发指令，环境：prod |
|
||
| build | 编译指令（type-check + build-only） |
|
||
| test:unit | 单测指令 |
|
||
| build-only | 仅编译指令 |
|
||
| type-check | ts类型校验 |
|
||
| lint | eslint校验 |
|
||
| lint:fix | eslint校验（带自动fix） |
|
||
|
||
## 使用
|
||
|
||
- 确保你安装了正常的包管理工具
|
||
pnpm@10+
|
||
|
||
- 安装依赖
|
||
|
||
```
|
||
pnpm install
|
||
```
|
||
|
||
- 运行项目
|
||
|
||
```
|
||
pnpm run dev
|
||
```
|
||
|
||
> 你可以自由选择不同的环境指令
|
||
|
||
- 编译项目
|
||
|
||
```
|
||
pnpm run build
|
||
```
|
||
|
||
## 技术栈及主要依赖说明
|
||
|
||
主要技术栈：vite + vue3 + vue-router
|
||
|
||
### 三方依赖说明
|
||
|
||
| 名称 | 版本 | 作用 | 备注 |
|
||
| ------------------------------------------------------------------------------------- | ----- | ------------------------ | --------------------------------------------------------------------------------- |
|
||
| [element-plus-cisdi](https://design.cisdigital.cn/plus/zh-CN/guide/installation.html) | 1.0.0 | 基础UI组件库 | element-plus定制版 |
|
||
| vue | 3.5+ | UI框架 | |
|
||
| pinia | 2+ | 状态管理 | |
|
||
| vite | 6+ | 前端开发与构建工具 | |
|
||
| eslint | 9+ | 代码格式化，风格统一管理 | 提交校验：husky + lint-staged + eslint<br />校验规则使用@eslint/config |
|
||
| @commitlint/cli | 19+ | commit内容校验 | 提交校验：husky + commitlint<br />校验规则使用@commitlint/config-conventional@19+ |
|
||
| vue-router | 4+ | 路由库 | |
|
||
| dayjs | 1.11+ | 时间工具库 | |
|
||
| lodash-es | 4+ | 常见工具库 | |
|
||
| @vueuse/core | 12+ | 常见hook库 | |
|
||
| vitest | 3+ | 单元测试 | |
|
||
| echarts | 5+ | 图表库 | |
|
||
| vue-i18n | 10+ | 多语言管理库 | |
|
||
| unocss | 66+ | 原子类css | |
|
||
| husky | 9+ | git hook | |
|
||
|
||
### 自有依赖说明
|
||
|
||
| 名称 | 作用 | 备注 |
|
||
| -------------------------- | ---------------- | --------------------------------------- |
|
||
| @lingshu/icon | icon组件 | 用于接入字体图标 |
|
||
| @lingshu/vite-plugin-msw | 本地mock数据模拟 | 通过vite变量`VITE_ENABLE_MOCK`启用/关闭 |
|
||
| @lingshu/vite-plugin-share | 共享依赖接入 | 用于接入通用共享依赖 |
|
||
| @lingshu/integration-vue3 | 主子应用对接插件 | |
|
||
| @lingshu/language-lib | 多语言管理库 | 由于后端支持原因，未完善，后续统一修改 |
|
||
| @lingshu/request-lib | 请求库 | axios二封产物 |
|
||
| @lingshu/theme-lib | 多主题插件 | |
|
||
|
||
> 版本建议：若依赖共享则跟随共享版本走，否则以最新版本为准
|
||
|
||
## 基础目录
|
||
|
||
```
|
||
.
|
||
├── .husky/ # 存储Git钩子脚本，用于自定义Git操作行为
|
||
├── .vscode/ # 存储Visual Studio Code的配置文件，如代码片段、设置等
|
||
├── coverage/ # 存储代码覆盖率报告，用于评估测试的有效性(可能存在)
|
||
├── dist/ # 存储构建后的分发文件，通常是生产环境部署的文件
|
||
├── node_modules/ # 存储项目依赖的Node.js模块
|
||
├── public/ # 存储公共资源文件，如网站图标等
|
||
├── src/ # 存储源代码
|
||
| ├── api/ # api请求封装
|
||
│ ├── assets/ # 存储静态资源文件，如图像、样式表等
|
||
│ │ ├── dark # 暗色主题静态资源
|
||
│ │ ├── light # 亮色主题静态资源
|
||
│ ├── components/ # 存储可复用的Vue组件
|
||
│ ├── constants/ # 存储全局常量
|
||
│ ├── directives/ # 存储自定义Vue指令
|
||
│ ├── hooks/ # 存储自定义Vue钩子函数
|
||
│ ├── icons/ # 通用字体图标资源
|
||
│ ├── locales/ # 当前库多语言管理以及非自研三方库多语言管理（如：element-plus）
|
||
│ ├── router/ # 存储Vue Router的路由配置
|
||
│ ├── stores/ # 存储Vuex状态管理的配置
|
||
│ ├── styles/ # 存储通用css
|
||
│ ├── type-utils/ # 通用ts类型辅助函数
|
||
│ ├── types/ # 存储通用ts类型
|
||
│ ├── utils/ # 存储工具函数和实用程序
|
||
│ │ ├── requestUtils.ts # 请求库工具
|
||
│ ├── views/ # 存储页面级别的Vue组件
|
||
│ ├── App.vue # 根Vue组件，通常包含整个应用的布局
|
||
│ ├── build-import.ts # production模式导入内容
|
||
│ ├── dev-import.ts # 非production导入内容
|
||
│ └── main.ts # 入口文件，用于启动和编译Vue应用
|
||
├── .env # 存储通用环境变量
|
||
├── .env.dev # 存储dev环境变量
|
||
├── .env.pre # 存储pre环境变量
|
||
├── .env.prod # 存储prod环境变量
|
||
├── .env.qa # 存储qa环境变量
|
||
├── .gitattributes # Git属性文件，用于设置文件属性和行为
|
||
├── .gitignore # Git忽略文件，指定Git不应跟踪的文件和文件夹
|
||
├── index.html # HTML入口文件，通常是Web应用的入口页面
|
||
├── package.json # 项目配置文件，包含依赖列表、脚本和元数据
|
||
├── .npmrc # npm配置文件，用于设置npm的配置选项
|
||
├── .nvmrc # nvm配置文件，用于设置node的版本
|
||
├── pnpm-lock.yaml # pnpm锁文件，用于确保依赖版本的一致性
|
||
├── README.md # 项目自述文件，包含项目介绍、安装和使用指南
|
||
├── tsconfig.json # TypeScript配置文件，设置TypeScript的编译选项
|
||
├── .env.d.ts # 环境变量的TypeScript声明文件
|
||
├── tsconfig.app.json # TypeScript配置文件，用于配置应用程序的编译选项
|
||
├── tsconfig.node.json # TypeScript配置文件，用于配置Node.js环境的编译选项
|
||
├── tsconfig.vitest.json # TypeScript配置文件，用于配置Vitest测试框架的编译选项
|
||
├── vite.config.ts # Vite配置文件，设置Vite构建工具的选项
|
||
├── commitlint.config.ts # Commitizen配置文件，设置提交消息的规范
|
||
├── eslint.config.mts # ESLint配置文件，设置代码规范和风格
|
||
├── uno.config.ts # UnoCSS配置文件，设置UnoCSS的选项
|
||
└── vitest.config.ts # Vitest配置文件，设置Vitest测试框架的选项
|
||
```
|
||
|
||
## 接入主应用
|
||
|
||
to-do
|
||
|
||
## 环境
|
||
|
||
### 环境说明
|
||
|
||
项目模板中预置了多个环境配置文件，可视实际开发情况进行使用
|
||
|
||
- `.env`：通用环境配置
|
||
- `.env.local`: 通用环境配置，但是会被git忽略
|
||
- `.env.dev`：dev环境配置
|
||
- `.env.pre`：pre环境配置
|
||
- `.env.prod`：prod环境配置
|
||
- `.env.qa`：qa环境配置
|
||
|
||
> 运行相应指令即可启动对于环境文件的环境变量
|
||
>
|
||
> 如：启动 `pnpm run dev:qa`
|
||
>
|
||
> 可使`.env.qa`文件中的环境变量生效
|
||
>
|
||
> 更详细的说明可参考：[vite 环境变量](https://vitejs.cn/vite5-cn/guide/env-and-mode.html#env-variables)
|
||
|
||
### 环境变量说明
|
||
|
||
**各环境文件配置**
|
||
|
||
| 属性名称 | 作用 |
|
||
| ------------- | --------------------------------------------------- |
|
||
| VITE_API_BASE | 请求代理前缀，会在`vite.config.ts`的proxy配置中使用 |
|
||
|
||
**local本地化配置**
|
||
|
||
`.env.local`文件不会上传到git仓库，主要用于存放一些在开发过程中需要频繁修改的属性
|
||
|
||
| 属性名称 | 作用 |
|
||
| ---------------- | ------------ |
|
||
| VITE_ENABLE_MOCK | 是否开启Mock |
|
||
|
||
## vscode插件
|
||
|
||
本模板内置推荐项：
|
||
|
||
| 插件 | 作用 |
|
||
| ------------ | ------------------------- |
|
||
| unocss | 原子类css的代码提示及补全 |
|
||
| eslint | 格式化插件 |
|
||
| vitest | 单测插件 |
|
||
| vue-official | vue代码提示 |
|
||
|
||
非内置推荐项：
|
||
|
||
| 插件 | 作用 |
|
||
| ------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||
| git-commit-plugin | commit交互式填写工具，可便捷完成commit内容 |
|
||
| var-translate-en | 变量命名工具。支持单驼峰、双驼峰、下划线、全大写等格式；支持中译英，英译英；支持阿里等服务提供商的免费百万token |
|
||
| vscode-code-to-type | js/json转ts类型定义 |
|
||
| code-spell-checker | 单词拼写检查 |
|
||
|
||
> 相关配置文件放于 `.vscode/extensions.json`和`.vscode/settings.json`中，若需要进一步定制化，可修改其文件配置
|
||
|
||
## 多主题接入说明
|
||
|
||
见[ones链接](https://ones.cisdigital.cn/wiki/#/team/SKG3mSQb/space/4W7YLcLr/page/4MCTXeA6)
|
||
|
||
## 其他说明
|
||
|
||
- `.gitkeep`文件用于在git仓库中保证目录的留存，实际使用可删除
|
||
- views和router目录下存放及使用的一些页面文件属于示例文件，可删除
|
||
- 目前项目未增加独立部署时的编译指令，可根据需求自行添加
|
||
|
||
## 常见问题
|
||
|
||
### 1、当存在全局样式的时候，如何在接入主应用的情况下生效？（如Dialog元素挂载到body下样式失效）
|
||
|
||
使用插件，示例配置如下：
|
||
|
||
@lingshu/vite-plugin-head-style插件废弃;
|
||
|
||
具体说明文档可见：https://ones.cisdigital.cn/wiki/#/team/SKG3mSQb/space/4W7YLcLr/page/Xzhqbd8P
|
||
|
||
### 2、报错 Failed to fetch dynamically imported module: xxx
|
||
|
||
1、检查网络请求中是否有报错，根据报错信息对相关模块进行处理
|
||
2、请不要使用AutoImport插件对通用排包依赖进行处理（即@lingshu/vite-plugin-share处理的依赖）
|
||
|
||
## to-do
|
||
|
||
- 多语言发布脚本，引用新的多语言npm库
|
||
|
||
## provide
|
||
|
||
1、中间设计器组件可使用
|