快速上手
本节将介绍如何在全局环境安装 @winner-fed/create-project 和通过命令行快速的生成项目。
环境搭建
- 需要在本地安装 Node.js 和 Git。
- 推荐使用 vscode 作为代码编辑器，安装以下插件可以更好的体验脚手架：
- Vue Language Features (Volar)（Vue3 开发必备）
- ESLint（Javascript 代码检查）
- Stylelint（CSS 代码检查）
- Prettier - Code formatter（代码格式化）
创建项目
命令
通过以下指令创建一个新项目：
pnpm dlx @winner-fed/create-project project-name
yarn create @winner-fed/project project-name
npm init @winner-fed/project@latest project-name
# 相当于
npx @winner-fed/create-project@latest project-name
注意
- 本地安装 Node 版本有所限制， "^14.13.1 || >=16.0.0"
- 在使用 npm 时，版本号(@latest)不能被省略，否则 npm 可能解析为包的缓存版本和过期版本。
参数选项
创建项目时，可用的参数如下：
| 参数 | 描述 |
|---|---|
| --no-git | 创建项目，但不初始化 Git |
| --install | 创建项目，自动安装依赖 |
选择特性
使用创建命令会提示一系列问题， ：
1. Select a framework?（选择 Framework）
- Vue 2
- Vue 3
- miniprogram
2. Select a small program development framework? （选择小程序开发的技术框架）
- Taro
- uni-app
- Hola
3. Choose whether your app is a PC or a mobile?（选择应用是基于 PC 端还是移动端）
- mobile
- H5 离线包
- PC
提示
当选择 H5 离线包 的时候，构建工具会默认选择为 bundle(webpack)。
这是因为 Vite 工具的特性决定的。原因如下：
Vite 没有为传统模块系统设计，默认输出 <script type=module>，也就是 ES Modules。ES Modules 是其特性基线。它是不支持文件系统访问的，需要使用一个 HTTP 服务器来提供脚本文件（也就是浏览器错误日志中的需要 http/https 的 scheme...） 。或者，可以在原生应用注入自定义 scheme 来使用内嵌页面（example-app:// 什么的），这样可以正常激活 ES Modules 特性，从一开始规避这个问题。 如果实在希望使用 Vite 做开发，同时只能使用 file:///，可以使用 @vitejs/plugin-legacy 生成 nomodule 的版本，然后对 dist/index.html 做如下改动：
- 移除
<script type=module>元素 - 移除其他
<script>的 nomodule 属性 - 移除
<script id=vite-legacy-entry>元素的内容，并把 data-src 属性名改为 src - 移除 SystemJS loader 代码（那个压缩到一行的
<script>） - 修改所有资源地址为相对地址（例如把 /assets/index-legacy.xxxx.js 改为 ./assets/index-legacy.xxxx.js，注意还有 CSS 文件）
综上所述，这种改动比较多，而且要测试充分。不推荐。
4. Select a mobile development platform?（选择移动开发平台）
- GMU
- mPaaS
提示
当选择 H5 离线包 的时候，此选项会出现。
这个时候会要求输入 离线包 ID 及 离线包名称。
其中，这两个值都是有校验规则的。
在 GMU 平台中，
- 离线包 ID：4-8 位的小写英文字母或数字，注意唯一性
- 离线包名称：1-10 位的中英文字符或数字
在 mPaaS 平台中，
- 离线包 ID：8 位的数字，注意唯一性
- 离线包名称：无规则限制
5. Add TypeScript?（是否需要使用 TypeScript）
6. Choose whether your build tools is bundle(webpack) or bundless(vite)?（选择构建工具）
- bundle(webpack)
- bundless(vite)
提示
- vue-cli 升级了最新的 5.x，其中 webpack 版本为 5.x
- vite 使用 2.x
7. Select a UI Framework（选择 UI 组件库）
- Element UI
- Ant Design Vue
- Hui
- WinUI
- Vant
提示
WinUI 和 Vant，适用于 移动端 H5，离线包
- Vue 2.x 使用 WinUI 1.x，Vue 3.x 使用 WinUI 2.x
- Vue 2.x 使用 Vant 2.x，Vue 3.x 使用 Vant 3.x
element-ui，ant-design-vue，适用于 PC Web
- Vue 2.x 使用 element-ui，Vue 3.x 使用 element-plus
- Vue 2.x 使用 ant-design-vue 1.x，Vue 3.x 使用 ant-design-vue 3.x
8. Select a mobile layout adaptation plan?（选择移动端布局适配方案）
- rem
- vw
提示
可以自由地用 px 去开发。相关配置在 postcss.config.js
- rem：引入
postcss-pxtorem及amfe-flexible - vw：引入
postcss-px-to-viewport
9. Select a Version control tool?（选择版本管理工具）
- Git
- SVN
10. Add Mirror Source Support?（是否使用公司镜像源）
提示
由于公司内使用了私服镜像源，因此会生成两个文件 .npmrc、.yarnc，用于指定项目所需要的指定镜像源地址。请务必要根据实际项目需求，动态调整文件里的地址。
11. Add See Package Support?（是否支持 SEE 平台发布物及 Docker 发布物）
提示
当选择了第 9 步骤为 yes 时，此选项才会出现。
12. Select a collection of subsystem types?（选择子系统类型集合）
提示
当选择第 1 步骤为Vue 2, 第 3 步骤为 pc, 第 6 步骤为 webpack 时会出现。
- 支持生成 qiankun 子系统，可以运行在以 qiankun 主系统中。
- 支持生成 Hui pro 1.x 的子系统，可以运行在以操作员中心或者财富中台作为外框架的主系统中
- Vite 作为构建工具的时候，不支持生成 Hui pro 1.x 的子系统，不支持生成 qiankun 子系统
- Vue3 不支持 Hui pro 1.x，暂不支持 qiankun
- public/frame 相关的文件来源于财富中台外框架的样式文件，为了尽量还原业务子系统嵌入外框架运行时的样式
- 当选择 qiankun 子应用时，新增 script 命令
npm run dev:microFront，该命令用于同时支持 Hui pro 1.x 和 qiankun 子应用的系统时，去除 public/frame 样式。并且将路由跳转自动转为快捷选项。在打成生产包时，会将开发使用的快捷跳转组件移除。
13. Add Vitest for Unit Testing?（是否支持 Vitest 作为单元测试工具）
提示
当选择了第 6 步骤（构建工具）为 bundless(vite) 时，此选项才会出现。
14. Add Jest for Unit Testing?（是否支持 Jest 作为单元测试工具）
提示
当选择了第 6 步骤（构建工具）为 bundle(webpack) 时，此选项才会出现。
安装依赖
- 输入以上命令后，模板文件会自动创建名字为 [project-name] 的文件夹，并将模板文件复制到此文件夹内。
- 选择 Git 的时候，会自动初始化 Git 仓库。
- 选择安装包管理工具，推荐选择：
优先级：yarn > npm
提示
建议通过重新指定 registry 来解决 npm 安装速度慢的问题。若还是不行，可使用 yarn 替代 npm。
开发环境
根据安装后的相关提示，输入相关命令以继续：
npm run bootstrap
npm run dev
#
npm run serve
npm run lint
npm run lint:style
npm run report
提示
在 Git 仓库里，通常情况下 ESLint 与 Stylelint 没必要单独执行，husky 提供的 git commit 钩子会在提交代码时，对缓存区里的代码做校验，这也会节省很多时间。