微信小程序从 0 到 1 入门项目

这是一个适合零基础开发者的 Taro + React + TypeScript 微信小程序项目模板。你后续会用 React 组件方式开发页面，再编译成微信小程序代码进行预览和发布。

当前首页已经改成了一版“设备绑定首页（无设备状态）”业务样式，方便你直接在这个基础上继续接真实接口和页面跳转。 项目里也已经开始整理公共能力：

• 颜色统一收口到全局主题变量，后续页面尽量不要再写散落的十六进制颜色
• 通用 UI 优先拆成可复用组件，方便后续多页面共用

当前项目还新增了一版“睡眠报告演示页”，用于展示宝宝睡眠评分、呼吸状态、HRV、异常统计和 AI 分析建议等完整报告结构。

1. 目前已经包含什么

• Taro + React + TypeScript 项目骨架
• 首页设备绑定业务示例页面
• 睡眠报告演示页面
• 小程序 AppID 配置
• AGENTS.md 协作规则文件
• 从开发到发布的中文说明

2. 项目结构说明

.
├─ AGENTS.md
├─ README.md
├─ config
├─ package.json
├─ project.config.json
├─ tsconfig.json
└─ src
   ├─ app.config.ts
   ├─ app.scss
   ├─ app.tsx
   ├─ components
   │  └─ report
   │     ├─ chart-card.tsx
   │     ├─ chip-group.tsx
   │     ├─ daytime-prediction.tsx
   │     ├─ distribution-card.tsx
   │     ├─ insight-list.tsx
   │     ├─ kv-list.tsx
   │     ├─ metric-grid.tsx
   │     ├─ page-header.tsx
   │     ├─ score-overview.tsx
   │     ├─ section-card.tsx
   │     └─ summary-block.tsx
   └─ pages
      ├─ index
      │  ├─ index.config.ts
      │  ├─ index.scss
      │  └─ index.tsx
      └─ report
         ├─ index.config.ts
         ├─ index.scss
         ├─ index.tsx
         ├─ mock.ts
         ├─ report-utils.ts
         └─ types.ts

3. 你需要先准备什么

开发这个项目前，需要准备：

• 一个微信号
• 一个可登录的电脑
• 微信开发者工具
• 一个微信小程序账号
• Node.js 20 或更高版本
• npm 或 pnpm

微信开发者工具下载地址：

• 微信开发者工具

微信公众平台地址：

• 微信公众平台

4. 小程序 AppID 是什么

AppID 可以理解为你的小程序项目唯一身份标识。

• 真机预览、上传版本、提交审核时，通常都需要真实 AppID
• 使用开发者工具时，也建议直接绑定自己的真实项目
• 真正要上线时，一定要使用你自己的 AppID

5. 如何申请小程序 AppID

1. 打开 微信公众平台
2. 点击“立即注册”
3. 选择“小程序”
4. 按提示完成邮箱、主体、管理员等信息填写
5. 注册成功后，登录小程序后台
6. 在“设置”或“开发管理”相关页面找到 AppID

6. 如何配置 AppID

当前项目中，AppID 配置在：

• project.config.json

当前已经配置为你的真实 AppID：

"appid": "wx2e6e4000b0ef29d9"

注意：

• 这是你的小程序身份标识，请不要随便改成别人的
• 如果以后换项目主体，再替换为新的 AppID

7. 这个项目为什么要先编译

因为你要求使用 React + TypeScript，这里采用的是 Taro。

这意味着：

• 你平时编写的是 src/ 里的 React 代码
• 然后用命令把 React 代码编译成微信小程序代码
• 微信开发者工具最终读取的是编译产物目录 dist/

8. 先安装依赖

先在项目根目录打开终端，执行：

npm install

如果你使用 pnpm，也可以执行：

pnpm install

9. 启动微信小程序开发编译

安装依赖完成后，执行：

npm run dev:weapp

这个命令会做两件事：

• 把 src/ 里的 React + TypeScript 代码编译成微信小程序代码
• 持续监听文件变化，你改代码后会自动重新编译

首次编译成功后，会生成：

• dist/

10. 如何在微信开发者工具里打开项目

1. 安装并打开微信开发者工具
2. 选择“导入项目”
3. 项目目录选择当前文件夹： C:\Users\a\Documents\New project 3
4. AppID 使用： wx2e6e4000b0ef29d9
5. 导入项目
6. 如果开发者工具提示编译目录相关问题，确认你已经先运行过： npm run dev:weapp

如果你要重点查看新增的睡眠报告页：

• 先进入首页
• 点击底部“报告”
• 或点击首页里的“查看睡眠报告”

11. 项目里的几个核心文件

• package.json 项目依赖和命令入口
• config/index.ts Taro 主构建配置
• src/app.config.ts 小程序页面注册和窗口配置
• src/app.tsx React 应用入口
• src/pages/index/index.tsx 首页 React 页面
• src/pages/index/index.config.ts 首页配置
• src/pages/index/index.scss 首页样式

12. 当前首页做了什么

现在首页已经不是默认演示页，而是一个“设备绑定首页（无设备状态）”业务页，包含：

• 顶部登录入口
• 已关联设备数量展示
• 扫码添加设备按钮
• 蓝牙搜索附近设备按钮
• 绑定状态展示区
• 绑定前提示卡片
• 底部导航视觉样式

当前首页已经接入了部分小程序能力：

• 扫码按钮会调用微信小程序扫码能力
• 蓝牙按钮会先检查定位权限，再尝试打开蓝牙搜索
• 如果开发环境中暂时搜不到真实设备，页面会用前端占位设备演示完整绑定流程

这些内容当前仍然属于前端演示和占位实现，方便你后续继续接：

• 登录页
• 扫码解析接口
• 真实蓝牙设备筛选与配对
• 设备列表
• 报告、消息、我的等页面

12.1 当前报告页做了什么

现在项目里已经新增一个独立的“睡眠报告页”，主要包含：

• 首页底部“报告”入口跳转
• 首页主体里的“查看睡眠报告”快捷入口
• 日报 / 周报 / 月报 三种时间维度切换
• 日期、房间、设备三个筛选条件
• 睡眠评分总览
• 睡眠趋势图和睡眠分数趋势图
• 9 项核心指标卡片
• AI 睡眠分析和改善建议
• 异常统计、HRV、心率散点图、呼吸波形图
• 低氧统计、打鼾监测、异常事件散点图
• 睡眠结构、自主神经分析、日间状态预测

说明：

• 当前报告页使用本地 mock 数据驱动
• 图表是轻量前端演示实现，没有引入大型图表依赖
• 各板块尽量拆成了可复用组件，便于你继续改
• 分享功能当前还是前端占位提示，后续可再接真实能力

13. 你接下来最常做的开发动作

改公共主题色

编辑：

• src/styles/theme.scss

改通用组件

编辑：

• src/components

改页面文案和逻辑

编辑：

• src/pages/index/index.tsx

改报告页

编辑：

• src/pages/report/index.tsx

改报告页 mock 数据

编辑：

• src/pages/report/mock.ts

改报告页组件

编辑：

• src/components/report/ 目录下的组件文件

改全局样式

编辑：

• src/app.scss

新增页面

你以后可以在 src/pages/ 下新增页面目录，比如：

src
└─ pages
   └─ profile
      ├─ index.config.ts
      ├─ index.scss
      └─ index.tsx

然后记得在 src/app.config.ts 里注册页面路径。

14. 本地预览与真机调试

本地预览

• 保持 npm run dev:weapp 在运行
• 在微信开发者工具里查看编译后的模拟器效果
• 扫码和蓝牙相关能力更推荐使用真机调试，因为开发者工具里不一定能完整模拟真实权限和设备搜索环境

如果你在改报告页，推荐同步检查：

• 报表维度切换后数据有没有变化
• 日期、房间、设备切换后内容有没有同步
• 点击图表节点后提示值有没有更新

真机预览

1. 确保已填写真实 AppID
2. 点击开发者工具中的“预览”
3. 使用管理员或绑定开发者微信扫码
4. 在手机里查看效果
5. 如果要测试蓝牙绑定，请同时确认手机蓝牙和定位权限已经打开

15. 上传、提交审核和发布

当你开发完成后，一般流程如下：

1. 先执行生产编译：

npm run build:weapp

2. 在微信开发者工具中点击“上传”
3. 填写版本号，例如 0.1.0
4. 填写版本备注，例如“初版首页完成”
5. 登录微信公众平台
6. 在“版本管理”中找到刚上传的开发版本
7. 提交审核
8. 审核通过后，点击发布

16. 常见问题

1. npm install 失败怎么办

先确认：

• 电脑已安装 Node.js
• 网络可以访问 npm
• 终端运行目录是： C:\Users\a\Documents\New project 3

2. 为什么微信开发者工具里看不到页面

常见原因有：

• 还没有先运行 npm run dev:weapp
• dist/ 还没生成
• 编译报错导致输出失败
• 页面没有在 src/app.config.ts 里注册

3. 为什么上传不了

常见原因有：

• 当前微信号不是该小程序项目成员
• 小程序主体信息未完成
• 类目、服务内容或合规信息未补全
• 代码中仍有编译错误或配置问题

4. 为什么接口请求失败

如果以后你接后端接口，微信小程序通常要求：

• 配置合法域名
• HTTPS
• 后台服务正常可访问

5. 如何验证报告页里的纯逻辑

当前项目新增了一个最小测试命令，用来验证报告页里的纯逻辑函数，比如：

• 睡眠评分等级映射
• 状态颜色映射
• mock 数据选择逻辑

执行：

npm run test:report

17. 建议你下一步怎么做

如果你是零基础，推荐按这个顺序继续：

1. 先跑通 npm install
2. 再跑通 npm run dev:weapp
3. 看懂首页 index.tsx 怎么写
4. 再加第二个页面
5. 再学页面跳转
6. 最后接接口和发布

18. 后续我可以继续帮你做什么

接下来你可以继续让我直接帮你：

• 改造成你真正想做的小程序业务
• 新增页面和底部导航
• 对接后端接口
• 加登录、表单、列表、详情页
• 配置发布前需要的内容

如果你愿意，我们下一步就可以直接开始做你的正式业务页面。