math.miniapp

知了数学 · 小程序

math.client-pc 的教师工作台小程序，使用 Taro 4、React 18、TypeScript、Vite 和 SCSS。此目录为独立 Git 仓库，使用 pnpm 管理依赖。

当前仅实现首页和「我的」页面，所有环境均使用虚构的本地演示数据，不调用后端、不读取或上传文件、不播放真实视频。上传入口、消息、题目讲解、账号信息、密码校验与退出/重新进入演示账号支持本地交互；退出不代表真实鉴权。

安装与预览

要求 Node.js 22.18+、pnpm 10.34.9（已在 packageManager 中固定）。React 18 为当前 Taro 官方插件支持的版本，未沿用 PC 端的 React 19。

pnpm install --frozen-lockfile
pnpm dev

如果本机全局 pnpm 不是 10.34.9，可将命令前缀换成 npx --yes pnpm@10.34.9，例如 npx --yes pnpm@10.34.9 dev，无需改动全局安装。

先执行 pnpm dev 完成首次编译，再在微信开发者工具中直接导入 math.miniapp 根目录。根目录的 project.config.json 已将 miniprogramRoot 设为 dist/，修改源码后会自动重新编译。pnpm build:dev 可生成一次性的开发环境产物。

默认 touristappid 用于本地预览；需要真机或正式上传时，在微信开发者工具中使用自己的公开 AppID，不在本项目填写 AppSecret。也支持单独导入 dist/，该目录的工程配置可用进程环境变量覆盖 AppID：

$env:TARO_APP_ID = '你的小程序AppID'
pnpm build:test

浏览器辅助预览：pnpm dev:h5，访问 http://127.0.0.1:10086。H5 用于快速查看布局与交互，微信端效果仍需在开发者工具及真机上确认。构建命令只编译本地文件，不会上传或发布小程序。

三套打包环境

环境	打包命令	产物目录
开发	pnpm build:dev	dist/
测试	pnpm build:test	dist/
正式	pnpm build:production（或 pnpm build）	dist/

pnpm build:all 依次构建开发、测试、正式环境，最终 dist/ 保留正式环境产物。测试环境监听构建使用 pnpm dev:test。切换环境前请先停止正在运行的监听构建，避免不同命令同时写入 dist/。需要恢复开发环境时运行 pnpm dev 或 pnpm build:dev。

H5 开发环境静态打包使用 pnpm build:h5，产物单独保存到 dist-h5/，避免覆盖小程序产物。

业务环境由构建命令选择，脚本显式传递 --mode development/test/production，由 Taro 加载对应的 .env.* 文件，并设置 APP_ENV。所有一次性打包均使用 NODE_ENV=production 优化，避免将 React 的构建模式和业务测试环境混用。三个环境共用 dist/，后一次构建覆盖前一次，微信开发者工具运行的是最近一次构建的环境。

dist/build-info.json 包含当前产物的环境、平台、版本、数据来源和构建时间；单独导入 dist/ 时微信工程名称也带环境后缀。所有环境的页面顶部均不显示环境标记；「关于」页可以查看环境和版本。三套环境目前都不含 API 地址，未来接接口时再分别添加公开配置，不能把密钥编译进前端。

根目录 project.config.json 用于直接导入仓库，同时作为产物工程配置的模板；构建生成的 dist/project.config.json 将 miniprogramRoot 设为 ./，也可直接导入。TARO_APP_ID 仅覆盖产物工程配置，不改写根目录配置。不同 AppID 不是区分环境的必要条件，微信体验版/正式版发布状态与业务环境是两个概念。

环境变量

文件	用途	提交 Git
.env.development	开发环境的公开值	是
.env.test	测试环境的公开值	是
.env.production	正式环境的公开值	是
.env / .env.local	可选的公共默认值 / 个人默认值	否
.env.<mode>.local	某个环境的个人覆盖值	否

同名变量的优先级从高到低：进程环境变量 → .env.<mode>.local → .env.<mode> → .env.local → .env。每个模式在独立构建进程中加载，build:all 不会沿用上一个环境文件的值。修改环境文件后需重启监听构建。

.env 文件格式本身不限制变量名前缀，但本项目使用 Taro 默认加载规则，自动加载并注入前端的自定义变量必须以完整的 TARO_APP_ 开头，单独的 TARO_ 前缀不够。任意名称的变量不会自动加载到业务代码；系统进程变量和框架内置变量另有用途。

例如，在本地 .env 中定义所有环境共用的公开变量（此文件不提交 Git）：

TARO_APP_APP_NAME=知了数学

在业务代码中可直接读取：

const appName = process.env.TARO_APP_APP_NAME

请使用完整的 process.env.TARO_APP_XXX 表达式，避免解构或动态键读取。同名值若存在于 .env.development 等优先级更高的文件中，将覆盖 .env，空字符串也会覆盖；需要使用公共默认值时，移除环境文件中的同名项。

三个环境文件已包含：

TARO_APP_ENV_LABEL=开发环境
TARO_APP_API_BASE_URL=
TARO_APP_ENABLE_DEBUG=true
TARO_APP_ID=touristappid

环境名称和调试开关分别按环境填写；接口地址目前留空，仍然只运行本地演示，不发请求。TARO_APP_ENABLE_DEBUG 必须为 true 或 false，不会自动打开调试工具。TARO_APP_ID 默认为游客 AppID；需要个人覆盖时在 .env.development.local 等文件中填写。

业务代码统一读取经过类型转换的配置：

import { appConfig } from '@/config/environment'

const apiBaseUrl = appConfig.apiBaseUrl
const enableDebug = appConfig.enableDebug // boolean

新增变量时，共用默认值放在本地 .env，不同环境的值放在对应 .env.*，并同步维护本节变量说明。需要统一暴露给业务代码的变量，更新 types/global.d.ts 的类型声明及 src/config/environment.ts 的读取/转换。需要构建时校验的变量同步维护 config/environments.ts 中的 readPublicConfig。不要在 TypeScript 中再硬编码三套环境值。Taro 以字符串注入环境变量，数字、布尔值需显式转换。

src/config/environment.ts 仍作为统一的类型化读取入口，「关于」页面正在使用它；它还负责将 TARO_APP_ENABLE_DEBUG 转换为布尔值。环境值来自 .env.*，这个文件不再维护三套配置。项目不保留额外的环境示例模板，变量说明直接维护在 README 和三套公开环境文件中。

TARO_APP_ 变量会打进前端包，只存放公开配置，不包含密钥。APP_ENV、NODE_ENV 由脚本控制，不在环境文件中设置。

验证

pnpm typecheck
pnpm lint
pnpm test
pnpm build:all
pnpm test
pnpm build:h5
pnpm test:e2e

单元测试覆盖环境校验、模式文件加载、个人与进程覆盖优先级、布尔值转换、统一输出目录、根目录导入配置、错误命令和当前产物的实际编译变量；可通过 EXPECTED_APP_ENV 指定产物应有的环境。E2E 使用本机 Chrome，覆盖 390px/320px 两种视口、两页导航、本地弹层、密码演示、退出与重新进入，并检查无业务 API 请求。未安装 Chrome 时需先安装，或修改 Playwright 的浏览器配置。

目录约定

• src/pages：首页和个人页；src/components：公共弹层、安全区和环境标记。
• src/data：本地演示数据及演示登录态，仅存内存，刷新恢复初始数据。
• config、scripts：环境与跨平台构建入口。
• tests：环境回归与浏览器交互验证。

品牌 Logo 复用工作区 math.client-pc/public/logo.png 的副本；底部导航和通知铃铛 PNG 图标由本项目绘制，通知图标可运行 scripts/create-notification-icon.ps1 重新生成。未引入 PC 端的 Electron、Ant Design 或 API 依赖。