---
url: /docs/guide/uniapp/structure.md
---
# 规范项目结构树（uniapp CLI 编译要求对照）

> 基准：`qm-frontend` `api` 分支（v18 真机验证通过的形态）。✅ = 符合规范；⚠️ = 可用但有改进项。

```
qm-frontend/                      # 仓库根 = 工程根（CLI 形态，HBuilderX 不参与编译）
├── package.json                  # ✅ @dcloudio/* 3.0.0-5020420260813001 精确锁版本（禁 caret）
├── vite.config.ts                # ✅ @dcloudio/vite-plugin-uni
├── tsconfig.json                 # ✅ @ 别名 → src
├── index.html                    # ✅ CLI 入口
├── src/                          # ✅ 源码根（UNI_INPUT_DIR）
│   ├── main.ts                   # ✅ createSSRApp 入口
│   ├── App.vue                   # ✅ 全局生命周期
│   ├── manifest.json             # ✅ appid __UNI__F1DDAB4 / 包名 cn.qingmulife.muhehealth
│   ├── pages.json                # ✅ 34 页注册 + tabBar(custom)
│   ├── pages/                    # ✅ 页面目录（分组建：login/index/ai/run/mine/detail/form/agreement/my-plan/webview）
│   │   ├── run/*.nvue            # ⚠️ 仅 2 页 .nvue（GPS 跑步 — 原生渲染 map 必需）；新页面默认 .vue
│   │   ├── */components/         # ✅ 页面私有子组件就地放（index/mine/info 均如此）
│   │   └── ...
│   ├── components/               # ✅ 全局 qm-* 组件 ×20（easycom 可考虑，见改进项 3）
│   ├── api/                      # ✅ 6 文件（agreement/device/login/splash/training/user）
│   │                             #    ⚠️ 仍未收敛：api/stats.ts 未建（首页直调）+ api/sport.ts 未建（改进项 1）
│   ├── utils/                    # ✅ request.ts（请求封装核心）/ storage / device / toastUtil 等 9 文件
│   ├── config/                   # ✅ BASE_URL 等环境配置
│   ├── static/                   # ✅ 静态资源（编译直拷）
│   └── uni_modules/              # ✅ uniapp 插件
└── BUILD-CLI.md                  # ✅ 编译说明（npm i → npm run build:app → dist/build/app）
```

## 编译要求对照（硬性）

| 要求 | 做法 | 违反后果 |
|---|---|---|
| 编译器精确锁版本 | `@dcloudio/*` 全系 `3.0.0-5020420260813001` | caret 拉 alpha → `createUniXKotlinCompilerOnce` 崩 |
| 隐藏依赖显式声明 | `sass`、`uni-uts-v1` 必须在 devDependencies | 首次 `npm i` 缺失即编译失败 |
| 根平铺不可用 | 源码必须在 `src/` | `UNI_INPUT_DIR=.` 根平铺模式 vite resolve 失败（已验证放弃） |
| 产物 | `npm run build:app` → `dist/build/app/` | = 基座 `assets/apps/__UNI__F1DDAB4/www/` 替换资源 |

## 改进项（按优先级）

1. **API 层收敛**：`device.ts` 已于 2026-09-18 建立（`device-list.vue` 已 import）——
   现在 `src/api/` 是 **6 文件**，**实际内联点只剩首页 `index.vue` 的 2 处**（`getTodayOverview` + `myTodayHealth`，
   按手册口径归「[页面直调](./api/page-direct.md)」）。后续按需补 `stats.ts` / `sport.ts` — 统一超时/鉴权/解包路径，便于契约文档对账
2. **pages.json 分包**：detail（13 页）+ mine（10 页）可拆 subPackages 减小主包体积（当前全在主包）
3. **easycom**：qm-\* 组件配置 easycom 自动注册，免逐页 import
4. **环境分型**：config/index.ts 目前单 BASE\_URL；建议 dev/prod 双环境注入（编译期 `process.env.NODE_ENV`）

> 注：以上均为「建议」，任何结构改动需走完整编译 + 真机回归（v18 基线）。