feat: initialize taro react typescript miniapp

2026-05-07 14:41:39 +08:00
commit 5a98d4afe7
18 changed files with 17606 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,12 @@
+/node_modules/
+/dist/
+/.swc/
+/.codex/
+/project.private.config.json
+
+# Legacy native mini program scaffold kept out of the Taro repo flow
+/app.js
+/app.json
+/app.wxss
+/pages/
+/sitemap.json
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,54 @@
+# AGENTS.md
+
+本文件用于约束后续在本项目内协作的 AI/自动化代理行为。
+
+## 项目目标
+
+这是一个面向新手的微信小程序项目，目标是：
+
+- 保持项目结构简单、易懂、易修改
+- 使用 `Taro + React + TypeScript` 作为核心技术栈
+- 所有说明尽量使用中文
+- 在保证可运行的前提下，减少复杂依赖
+
+## 协作原则
+
+- 修改代码前，先阅读现有文件，避免无意义重构。
+- 优先做小步修改，保持项目始终可运行。
+- 已确认使用 `React + TypeScript`，默认采用 `Taro` 作为微信小程序框架。
+- 不要在 `Taro` 之外再擅自引入新的大型框架或状态管理库，除非用户明确要求。
+- 对新手不友好的实现方式，要同时补充解释性注释或文档。
+- 涉及配置时，优先使用明确值，并在文档里写清楚用户需要修改的位置。
+
+## 文件与代码规范
+
+- 默认使用 UTF-8 编码。
+- 页面、组件和配置命名尽量贴合 `Taro` 与微信小程序习惯。
+- 目录结构优先采用：
+  - `src/pages/` 放页面
+  - `src/components/` 放可复用组件
+  - `src/utils/` 放工具函数
+  - `src/assets/` 放静态资源
+  - `config/` 放 Taro 构建配置
+- 默认使用 TypeScript 编写业务代码。
+- 样式优先使用 `.scss`，但保持简单，避免过度抽象。
+- 非必要不新增依赖，尤其避免在项目初期引入复杂状态管理、UI 大全家桶或重型工具链。
+
+## 修改边界
+
+- 可以新增或修改当前工作区内与本项目直接相关的文件。
+- 如需删除文件，必须严格遵守工作区已有的删除安全规则。
+- 不得擅自删除目录、批量删除文件、清空文件夹。
+- 不得覆盖用户未明确要求替换的重要配置、密钥或证书文件。
+
+## AppID 与发布相关
+
+- 不要伪造真实 `AppID`、密钥、证书、域名或后台接口地址。
+- 涉及 `AppID` 时，优先保留用户提供的真实值。
+- 如果项目需要上线步骤说明，必须同步更新 `README.md`。
+
+## 文档要求
+
+- 每次新增关键功能、配置步骤或部署步骤时，优先同步更新 `README.md`。
+- 文档写法以“零基础可照做”为标准，避免只写结论不写路径。
+- 如果修改了 Taro 的开发、编译、预览或发布流程，必须更新 `README.md` 中对应命令和目录说明。
--- a/README.md
+++ b/README.md
@@ -0,0 +1,276 @@
+# 微信小程序从 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. 后续我可以继续帮你做什么
+
+接下来你可以继续让我直接帮你：
+
+- 改造成你真正想做的小程序业务
+- 新增页面和底部导航
+- 对接后端接口
+- 加登录、表单、列表、详情页
+- 配置发布前需要的内容
+
+如果你愿意，我们下一步就可以直接开始做你的正式业务页面。
--- a/babel.config.js
+++ b/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [["taro", { framework: "react", ts: true }]]
+};
--- a/config/dev.ts
+++ b/config/dev.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from "@tarojs/cli";
+
+export default defineConfig({
+  env: {
+    NODE_ENV: '"development"'
+  },
+  mini: {},
+  h5: {}
+});
--- a/config/index.ts
+++ b/config/index.ts
@@ -0,0 +1,52 @@
+import { defineConfig } from "@tarojs/cli";
+
+export default defineConfig({
+  projectName: "wechat-miniapp-starter",
+  date: "2026-05-07",
+  designWidth: 750,
+  deviceRatio: {
+    640: 2.34 / 2,
+    750: 1,
+    828: 1.81 / 2
+  },
+  sourceRoot: "src",
+  outputRoot: "dist",
+  plugins: [],
+  defineConstants: {},
+  copy: {
+    patterns: [],
+    options: {}
+  },
+  framework: "react",
+  compiler: {
+    type: "webpack5"
+  },
+  cache: {
+    enable: false
+  },
+  mini: {
+    postcss: {
+      pxtransform: {
+        enable: true,
+        config: {}
+      },
+      url: {
+        enable: true,
+        config: {
+          limit: 1024
+        }
+      },
+      cssModules: {
+        enable: false,
+        config: {
+          namingPattern: "module",
+          generateScopedName: "[name]__[local]___[hash:base64:5]"
+        }
+      }
+    }
+  },
+  h5: {
+    publicPath: "/",
+    staticDirectory: "static"
+  }
+});
--- a/config/prod.ts
+++ b/config/prod.ts
@@ -0,0 +1,13 @@
+import { defineConfig } from "@tarojs/cli";
+
+export default defineConfig({
+  env: {
+    NODE_ENV: '"production"'
+  },
+  mini: {
+    optimizeMainPackage: {
+      enable: true
+    }
+  },
+  h5: {}
+});
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -0,0 +1,29 @@
+{
+  "name": "wechat-miniapp-starter",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Taro + React + TypeScript 微信小程序入门项目",
+  "scripts": {
+    "dev:weapp": "taro build --type weapp --watch",
+    "build:weapp": "taro build --type weapp"
+  },
+  "dependencies": {
+    "@tarojs/components": "^4.0.0",
+    "@tarojs/react": "^4.0.0",
+    "@tarojs/runtime": "^4.0.0",
+    "@tarojs/taro": "^4.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.0",
+    "@babel/preset-react": "^7.25.0",
+    "@tarojs/cli": "^4.0.0",
+    "@tarojs/plugin-framework-react": "^4.0.0",
+    "@tarojs/plugin-platform-weapp": "^4.0.0",
+    "@tarojs/webpack5-runner": "^4.0.0",
+    "@types/react": "^18.2.66",
+    "babel-preset-taro": "^4.0.0",
+    "typescript": "^5.4.5"
+  }
+}
--- a/project.config.json
+++ b/project.config.json
@@ -0,0 +1,46 @@
+{
+  "description": "新手微信小程序项目",
+  "packOptions": {
+    "ignore": [],
+    "include": []
+  },
+  "setting": {
+    "babelSetting": {
+      "ignore": [],
+      "disablePlugins": [],
+      "outputPath": ""
+    },
+    "bundle": false,
+    "coverView": true,
+    "es6": true,
+    "enhance": true,
+    "ignoreUploadUnusedFiles": true,
+    "minified": true,
+    "postcss": true,
+    "minifyWXSS": true,
+    "minifyWXML": true,
+    "minifyJS": true,
+    "compileHotReLoad": true,
+    "showShadowRootInWxmlPanel": true,
+    "uploadWithSourceMap": true,
+    "compileWorklet": false,
+    "uglifyFileName": false,
+    "packNpmManually": false,
+    "packNpmRelationList": [],
+    "localPlugins": false,
+    "disableUseStrict": false,
+    "useCompilerPlugins": false,
+    "condition": false,
+    "swc": false,
+    "disableSWC": true
+  },
+  "compileType": "miniprogram",
+  "libVersion": "3.6.3",
+  "appid": "wx2e6e4000b0ef29d9",
+  "miniprogramRoot": "dist/",
+  "projectname": "wechat-miniapp-starter",
+  "simulatorType": "wechat",
+  "condition": {},
+  "simulatorPluginLibVersion": {},
+  "editorSetting": {}
+}
--- a/src/app.config.ts
+++ b/src/app.config.ts
@@ -0,0 +1,10 @@
+export default defineAppConfig({
+  pages: ["pages/index/index"],
+  window: {
+    navigationBarTitleText: "新手小程序",
+    navigationBarBackgroundColor: "#1AAD19",
+    navigationBarTextStyle: "white",
+    backgroundTextStyle: "light",
+    backgroundColor: "#f6f7fb"
+  }
+});
--- a/src/app.scss
+++ b/src/app.scss
@@ -0,0 +1,21 @@
+page {
+  background: #f6f7fb;
+  color: #1f2937;
+  font-size: 32rpx;
+}
+
+.page {
+  min-height: 100vh;
+  padding: 40rpx 32rpx 60rpx;
+  box-sizing: border-box;
+  background:
+    radial-gradient(circle at top right, rgba(26, 173, 25, 0.15), transparent 26%),
+    linear-gradient(180deg, #f7fbf5 0%, #f6f7fb 100%);
+}
+
+.card {
+  background: rgba(255, 255, 255, 0.96);
+  border-radius: 28rpx;
+  padding: 36rpx 32rpx;
+  box-shadow: 0 18rpx 48rpx rgba(15, 23, 42, 0.08);
+}
--- a/src/app.tsx
+++ b/src/app.tsx
@@ -0,0 +1,8 @@
+import "./app.scss";
+
+function App(props) {
+  const { children } = props;
+  return children ?? null;
+}
+
+export default App;
--- a/src/pages/index/index.config.ts
+++ b/src/pages/index/index.config.ts
@@ -0,0 +1,3 @@
+export default definePageConfig({
+  navigationBarTitleText: "首页"
+});
--- a/src/pages/index/index.scss
+++ b/src/pages/index/index.scss
@@ -0,0 +1,48 @@
+.title {
+  display: block;
+  font-size: 46rpx;
+  font-weight: 700;
+  line-height: 1.4;
+  margin-bottom: 16rpx;
+  color: #0f172a;
+}
+
+.subtitle {
+  display: block;
+  font-size: 28rpx;
+  line-height: 1.8;
+  color: #475569;
+}
+
+.section {
+  margin-top: 28rpx;
+}
+
+.section-title {
+  display: block;
+  font-size: 32rpx;
+  font-weight: 600;
+  margin-bottom: 14rpx;
+  color: #111827;
+}
+
+.list-item {
+  margin-bottom: 12rpx;
+  line-height: 1.8;
+  color: #334155;
+}
+
+.primary-btn {
+  margin-top: 28rpx;
+  border-radius: 999rpx;
+  background: linear-gradient(135deg, #1aad19 0%, #138a15 100%);
+  color: #ffffff;
+  border: none;
+}
+
+.tip {
+  display: block;
+  margin-top: 20rpx;
+  font-size: 24rpx;
+  color: #64748b;
+}
--- a/src/pages/index/index.tsx
+++ b/src/pages/index/index.tsx
@@ -0,0 +1,49 @@
+import { useState } from "react";
+import { Button, Text, View } from "@tarojs/components";
+import Taro from "@tarojs/taro";
+import "./index.scss";
+
+const steps = [
+  "先执行 npm install 安装依赖",
+  "再执行 npm run dev:weapp 启动编译",
+  "用微信开发者工具打开当前项目",
+  "继续在 React 页面里开发你的业务"
+];
+
+export default function Index() {
+  const [clicked, setClicked] = useState(false);
+
+  const handleStart = () => {
+    setClicked(true);
+    Taro.showToast({
+      title: "开始开发吧",
+      icon: "success"
+    });
+  };
+
+  return (
+    <View className="page">
+      <View className="card">
+        <Text className="title">欢迎开始你的第一个 React 小程序</Text>
+        <Text className="subtitle">
+          这是一个基于 Taro、React 和 TypeScript 的微信小程序模板，后续你写页面时会更接近前端 React 开发方式。
+        </Text>
+
+        <View className="section">
+          <Text className="section-title">推荐步骤</Text>
+          {steps.map((item, index) => (
+            <View className="list-item" key={item}>
+              {index + 1}. {item}
+            </View>
+          ))}
+        </View>
+
+        <Button className="primary-btn" onClick={handleStart}>
+          点击测试交互
+        </Button>
+
+        {clicked ? <Text className="tip">按钮事件已经触发，说明 React 页面逻辑正常运行。</Text> : null}
+      </View>
+    </View>
+  );
+}
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "strict": true,
+    "jsx": "react-jsx",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    },
+    "types": [
+      "@tarojs/taro",
+      "wechat-miniprogram"
+    ]
+  },
+  "include": [
+    "src",
+    "config",
+    "types"
+  ]
+}
--- a/types/global.d.ts
+++ b/types/global.d.ts
@@ -0,0 +1 @@
+declare module "*.scss";