# UniApp 前端脚手架

**Repository Path**: darkwinoom/uni-app-scaffold

## Basic Information

- **Project Name**: UniApp 前端脚手架
- **Description**: 这是一个使用 vue3 + ts + nutui-uniapp 搭建的 uni-app 示例，基于 create-uni，包含完整登录与鉴权功能，针对 H5、APP 与小程序进行了适配。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 3
- **Created**: 2024-09-22
- **Last Updated**: 2025-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: uni-app, vue3, nutui-uniapp, create-uni, TypeScript

## README

# uni-app 前端脚手架

> 目前正在开发中，每次提交的代码可能存在较大改动

这是一个使用 vue3 + ts + nutui-uniapp 搭建的 uni-app 示例，基于 create-uni，包含完整登录与鉴权功能，针对 H5、APP 与小程序进行了适配。

![预览](./docs/preview.png)

## 特色功能

- 基于 [create uni](https://github.com/uni-helper/create-uni) 开发，可不依赖 HBuilder 运行。既保留了 uniapp 的社区生态（可使用社区插件），也能受益于 vue3 + vite + ts 的优秀机制，强化开发体验；
- 使用 nutui-uniapp 构建UI，适配了uni-app, 使用 Vue 技术栈开发小程序应用，开箱即用，拥有丰富的业务组件；
- 本项目可独立使用 `mock` 运行，也可搭配项目 [tp8-server-scaffold](https://gitee.com/darkwinoom/tp8-server-scaffold) 作为其后端一同使用；

## 在线预览

![二维码](./docs/scan-qr.png)

请使用手机扫描上方二维码，或[点击这里访问](https://uni-app-scaffold.netlify.app/)

## 开发清单

- [x] 首页与动态页面基本样式
- [x] 商品与详情页面基本样式
- [x] 用户与登录页面基本样式
- [x] 使用mock用户登录与操作请求
- [ ] 【进行中】接入个人项目后端（tp8-serverscaffold）
- [ ] 【进行中】支持H5、微信小程序、IOS、安卓本地打包
- [ ] 支持手机号与微信登录
- [ ] 接入 chat-ai
- [ ] 接入 vitest 和 playwright
- [ ] 适配暗黑模式

## 页面兼容

兼容适配进行中，目前适配情况如下：

|         | H5  | IOS App | 安卓 App | 微信小程序 | 敬请期待 |
|---------|:---:|:-------:|:--------:|:---------:|:-------:|
| 首页    |  ✓  |         |          |           |         |
| 商城    |  ✓  |         |          |           |         |
| AI助手  |     |         |          |           |         |
| 频道    |     |         |          |           |         |
| 我的    |  ✓  |         |          |           |         |

## 技术栈

- vue3 + vite5 + typescript
- @dcloudio/uni-app + pinia
- nutui-uniapp + unocss + sass

## 安装使用

```sh
pnpm install
```

### 本地运行

```sh
pnpm dev
```

上述命令将开启 H5 平台运行，默认端口为8080（可通过 `.env` 文件修改）。您也可以使用以下命令运行到各平台：

```sh
pnpm dev:[平台名]
```

### 本地打包

可通过以下命令进行本地打包：

```sh
# 默认打包（h5平台）
pnpm build

# 指定平台打包
pnpm build:[平台名]
```

打包文件生成目录：`/dist/build/[平台名]`

### 平台说明

其它支持的命令可通过查看 `package.json` 文件确认，以下是各平台基础说明：

| 平台名                  | 说明                                    |
| ----------------------- | -------------------------------------- |
| app                     | app 平台，可指定 app-ios 或 app-android |
| h5                      | H5平台，生成html相关文件                 |
| mp-360                  | 360 小程序                             |
| mp-alipay               | 支付宝小程序                            |
| mp-baidu                | 百度小程序                              |
| mp-jd                   | 京东小程序                              |
| mp-kuaishou             | 快手小程序                              |
| mp-lark                 | 飞书小程序                              |
| mp-qq                   | qq 小程序                              |
| mp-toutiao              | 抖音小程序                              |
| mp-weixin               | 微信小程序                              |
| mp-xhs                  | 小红书小程序                            |
| quickapp-webview        | 快应用(webview)                        |
| quickapp-webview-huawei | 快应用华为                              |
| quickapp-webview-union  | 快应用联盟                              |

### 其它打包与运行

本项目也支持在 HBuilder 中运行，支持其默认的全部运行与打包操作。

此外，您也可以将打包生成的文件放置于各自源生平台中运行（如：Android Studio、Xcode、各小程序开发者工具等）。

## 目录说明

```md
├─ build               构建工具
├─ mock                mock目录
├─ src                 开发目录
│ ├─ api                 请求接口
│ ├─ components          全局组件
│ ├─ config              全局配置
│ ├─ layouts             全局布局，代替App.vue中template部分
│ ├─ pages               页面
│ ├─ static              静态资源
│ ├─ stores              状态管理
│ ├─ styles              全局样式
│ ├─ uni_modules         uniapp第三方插件
│ ├─ utils               全局工具
│ ├─ App.vue             入口页面
│ ├─ main.ts             入口文件
│ ├─ manifest.json       uniapp配置（自动生成）
│ ├─ pages.json          uniapp配置（自动生成）
│ ├─ theme.json          主题配置
├─types                全局类型配置
│
├─ .env                环境变量配置
├─ .env.development    环境变量配置（开发模式）
├─ .env.production     环境变量配置（生产模式）
├─ manifest.config.ts  uniapp配置
├─ pages.config.ts     uniapp配置
├─ ......              其它配置文件（如：package.json、tsconfig.json等）
```

## 配置说明

本项目配置包括 `uniapp配置`、`环境配置` 和 `项目配置`。

### uniapp配置

该配置为 uniapp 原生配置，配置文件 `manifest.config.ts` 和 `pages.config.ts`。

修改运行后会动态生成 `./src/manifest.json` 和 `./src/pages.json`，该文件无需进行管理。

可参考官方文档：<https://uniapp.dcloud.net.cn/collocation/pages.html>

### 环境配置

环境配置位于项目根目录，以 `.env` 开头，适配不同运行环境。完整配置信息如下：

```bash
# 平台本地运行端口号
VITE_PORT = 5173

# 默认请求地址
VITE_BASE_API = ""

# 是否启用本地mock
# 注意：建议仅在开发模式中启用 mock
VITE_USE_MOCK = true
```

### 项目配置

配置文件位于 `./src/config` 中：

| 配置文件         | 描述说明                                 |
| --------------- | ---------------------------------------- |
| index.ts        | 通用配置，全局生效                        |
| theme.scss      | 自定义主题配置                            |

**关于配置详情请查看对应文件字段注释。**

## Git 提交规范

- feat 增加新的业务功能
- fix 修复业务问题/BUG
- perf 优化性能
- style 更改代码风格, 不影响运行结果
- refactor 重构代码
- revert 撤销更改
- test 测试相关, 不涉及业务代码的更改
- docs 文档和注释相关
- chore 更新依赖/修改脚手架配置等琐事
- workflow 工作流改进
- ci 持续集成相关
- types 类型定义文件更改
- wip 开发中

## 开发环境

以下为个人开发环境参考：

- pnpm v10.12.3
- node v22.17.0
- npm v10.9.2

## 附：参考

- [uni-app 官方文档](https://uniapp.dcloud.net.cn/)
- [nutui-uniapp 官方文档](https://nutui-uniapp.pages.dev/guide/overview.html)
- [icones 图标库](https://icones.js.org/collection/all)
- [Css To UnoCss](https://to-unocss.netlify.app/)
- [create-uni](https://github.com/uni-helper/create-uni)