uniapp-template 是我从实际跨端项目中整理出的 uni-app Monorepo 模板。它的目标不是堆叠依赖，而是把页面、路由、接口生成、状态管理和多端构建这些高频基础工作组织清楚，让新项目从一套可检查的工程基线开始。
这是项目模板，不是开箱即用的完整业务系统。登录、权限、接口地址、隐私协议、应用标识和各平台配置都需要按真实项目补齐。
当前技术基线
- Node.js 18 或更高版本、pnpm 8 或更高版本
- Vue 3.5、TypeScript 5.9、Pinia 2
- Vite 5 与 uni-app CLI 3.0
- Wot Design Uni（以
uni_modules形式放在应用内） - ESLint、Prettier、Husky 与 lint-staged 相关依赖
精确版本以仓库中的 package.json 和 pnpm-lock.yaml 为准。README 只能描述设计意图，锁文件才是一次安装真正使用的依赖快照。
仓库结构
.
├── components/
│ ├── eslint-config/ # 共享 ESLint 配置
│ └── swagger-api-templates/ # Swagger/OpenAPI 代码生成 CLI
├── packages/
│ └── uni-template/ # uni-app 主应用
├── pnpm-workspace.yaml
└── package.json
主应用目前包含首页、个人中心、登录、协议和 Not Found 示例页，以及导航容器、请求、上传、授权、Pinia 状态、常用组合式函数和枚举工具。
快速开始
git clone https://github.com/ihopefulChina/uniapp-template.git
cd uniapp-template
pnpm install
pnpm --filter uni-template dev
微信开发者工具应导入 uni-app CLI 生成的微信小程序产物，而不是直接导入源码目录。输出路径可能随 CLI 版本和模式变化，请以终端日志为准。
开发 H5：
pnpm --filter uni-template dev:h5
生产构建与类型检查：
pnpm --filter uni-template build:mp-weixin
pnpm --filter uni-template build:h5
pnpm --filter uni-template type-check
仓库还提供 App、支付宝、百度、京东、快手、飞书、QQ、抖音和 Quick App 等脚本。这里要强调一个容易误解的边界：存在构建命令，不代表每一段业务代码都经过了所有平台的运行验证。 跨端项目发布前仍需对目标平台逐一测试。
为什么生成路由
uni-app 的页面入口集中在 pages.json，但业务代码如果到处手写字符串，会出现三个问题：
- 路径改名后，调用处无法得到类型提示。
- 主包与分包的路径拼接规则容易写错。
- TabBar 页面和普通页面的导航行为不同，却缺少统一信息源。
仓库中的 plugins/getRoute.mjs 会解析 JSONC 格式的 pages.json，合并主包与分包，然后生成：
routes.ts：页面路径、TabBar 清单、RoutePath和RouteKey。当前RouteKey能约束键名；生成器补上as const前，RoutePath的值类型仍会扩大为普通string。RouteParams.d.ts：各页面参数的类型入口。
手动执行：
pnpm --filter uni-template route
dev 命令会同时启动微信小程序开发构建和 watch-pages.mjs；dev:mp-weixin 只启动 uni-app 构建。页面配置变化后，监听脚本重新生成路由文件。
生成器会尽量保留 RouteParams.d.ts 中已经维护的字段，并为新路由补上默认的 Record<string, string>。默认类型只是迁移兜底；当页面依赖明确参数时，应主动改为更严格的接口。
当前脚本还没有完整的重复键检测与原子写入保护。接入 CI 前应补齐这两个边界，避免不同路径清理后映射到同一键名，或开发服务器读到半写入文件。
接口代码生成的正确边界
components/swagger-api-templates 提供 getapi 命令，底层使用 swagger-typescript-api。它解决的是“从 OpenAPI 契约生成类型和请求骨架”，不是替代接口评审。
在真实项目中，我建议：
- 接口文档地址、Token 与 Cookie 只通过本地环境或受控 CI 注入。
- 生成代码与手写业务封装分层，避免重新生成时覆盖业务逻辑。
- 每次生成后审查差异，尤其关注字段可空性、枚举、分页结构和错误码变化。
- 不把内网接口地址或凭证写进 README。
模板里值得复用的部分
页面与导航约束
统一维护路由路径和参数类型，减少魔法字符串；页面容器集中处理导航栏、间距和基础页面结构。
状态与组合式函数
Pinia 用于全局状态，局部异步流程和 UI 状态保留在组件或组合式函数内。仓库提供的 Hooks 是可修改的起点，不是所有业务场景的最终抽象。
请求与上传
请求层和上传层已经有基本目录结构，但真实项目必须补齐鉴权刷新、取消请求、重试边界、错误展示和监控，不应直接把示例配置当生产配置。
工作区工具
Monorepo 将应用、代码生成模板和共享配置放在同一仓库，便于统一安装与联调，同时避免把所有代码都塞进应用目录。
开始业务开发前的检查清单
- 修改
manifest.json中的应用名称、AppID、权限和平台配置。 - 确认请求基地址、错误码约定、鉴权与刷新 Token 流程。
- 替换登录、隐私协议、权限弹窗和审核文案。
- 替换 TabBar 图标、Logo、主题色与页面标题。
- 明确上传服务、对象存储配置和敏感信息注入方式。
- 在目标平台验证真机兼容、分包大小、隐私 API 和发布流程。
我会继续改进什么
- 给路由生成器补充结构化测试和重复键检测。
- 明确自动生成文件的校验与 CI 策略。
- 收紧示例 Hooks 的并发、错误与卸载边界。
- 按实际项目反馈继续减少模板中的隐式约定。