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

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

## 1. 目前已经包含什么

- `Taro + React + TypeScript` 项目骨架
- 首页 React 示例页面
- 小程序 `AppID` 配置
- `AGENTS.md` 协作规则文件
- 从开发到发布的中文说明

## 2. 项目结构说明

```text
.
├─ AGENTS.md
├─ README.md
├─ config
├─ package.json
├─ project.config.json
├─ tsconfig.json
└─ src
   ├─ app.config.ts
   ├─ app.scss
   ├─ app.tsx
   └─ pages
      └─ index
         ├─ index.config.ts
         ├─ index.scss
         └─ index.tsx
```

## 3. 你需要先准备什么

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

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

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

- [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)

微信公众平台地址：

- [微信公众平台](https://mp.weixin.qq.com/)

## 4. 小程序 AppID 是什么

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

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

## 5. 如何申请小程序 AppID

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

## 6. 如何配置 AppID

当前项目中，`AppID` 配置在：

- [project.config.json](C:/Users/a/Documents/New%20project%203/project.config.json)

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

```json
"appid": "wx2e6e4000b0ef29d9"
```

注意：

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

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

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

这意味着：

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

## 8. 先安装依赖

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

```bash
npm install
```

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

```bash
pnpm install
```

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

安装依赖完成后，执行：

```bash
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](C:/Users/a/Documents/New%20project%203/package.json)
  项目依赖和命令入口
- [config/index.ts](C:/Users/a/Documents/New%20project%203/config/index.ts)
  Taro 主构建配置
- [src/app.config.ts](C:/Users/a/Documents/New%20project%203/src/app.config.ts)
  小程序页面注册和窗口配置
- [src/app.tsx](C:/Users/a/Documents/New%20project%203/src/app.tsx)
  React 应用入口
- [src/pages/index/index.tsx](C:/Users/a/Documents/New%20project%203/src/pages/index/index.tsx)
  首页 React 页面
- [src/pages/index/index.config.ts](C:/Users/a/Documents/New%20project%203/src/pages/index/index.config.ts)
  首页配置
- [src/pages/index/index.scss](C:/Users/a/Documents/New%20project%203/src/pages/index/index.scss)
  首页样式

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

### 改页面文案和逻辑

编辑：

- [src/pages/index/index.tsx](C:/Users/a/Documents/New%20project%203/src/pages/index/index.tsx)

### 改全局样式

编辑：

- [src/app.scss](C:/Users/a/Documents/New%20project%203/src/app.scss)

### 新增页面

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

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

然后记得在 [src/app.config.ts](C:/Users/a/Documents/New%20project%203/src/app.config.ts) 里注册页面路径。

## 13. 本地预览与真机调试

### 本地预览

- 保持 `npm run dev:weapp` 在运行
- 在微信开发者工具里查看编译后的模拟器效果

### 真机预览

1. 确保已填写真实 `AppID`
2. 点击开发者工具中的“预览”
3. 使用管理员或绑定开发者微信扫码
4. 在手机里查看效果

## 14. 上传、提交审核和发布

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

1. 先执行生产编译：

```bash
npm run build:weapp
```

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

## 15. 常见问题

### 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
- 后台服务正常可访问

## 16. 建议你下一步怎么做

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

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

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

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

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

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