本项目将各业务子仓库以 Git subtree 方式内嵌于主仓库（目录 src/modules/*），无需再使用子模块初始化。
请严格按照下列步骤进行操作，否则会出现依赖安装失败、无法运行、缺少菜单等问题。
在开始之前，请确保你已经安装以下工具：
| 工具 | 版本要求 | 检查命令 |
|---|---|---|
| Git | ≥ 2.30 | git --version |
| Node.js | ≥ 20 | node -v |
| pnpm | ≥ 10 | pnpm -v |
| SSH Key | 已添加到 GitHub | 见下方配置说明 |
若你需要使用 pnpm modules:update 从上游 拉取 subtree 更新，远程仍为 SSH 地址，需配置 SSH；仅本地开发、不拉取上游时可不配置。
打开 PowerShell 或 Git Bash，执行：
ls ~/.ssh/id_rsa.pub若提示文件不存在，请生成：
ssh-keygen -t rsa -C "你的邮箱@example.com"一路按回车即可。
cat ~/.ssh/id_rsa.pub复制输出的整段内容。
- GitHub: https://github.com/settings/keys
点击 “New SSH Key” → 粘贴上面复制的公钥。
ssh -T git@github.com若提示：
Hi username! You've successfully authenticated...
说明 SSH 设置成功。
ls ~/.ssh/id_rsa.pub若无文件，执行：
ssh-keygen -t rsa -C "你的邮箱@example.com"eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsapbcopy < ~/.ssh/id_rsa.pub（命令会自动复制内容到剪贴板）
- GitHub: https://github.com/settings/keys
点击 “New SSH Key” → 粘贴上面复制的公钥。
ssh -T git@github.com使用 pnpm 命令运行该项目，安装pnpm
克隆主仓库后子仓库源码已包含在内。pnpm modules:init 仅作提示；若需从上游同步 subtree，请使用：
pnpm modules:update（需已配置 SSH，且会按当前主仓库分支名对应上游分支执行 git subtree pull；CI 会显式传入 2.11。）
确认 src/modules 下各目录存在后再安装依赖
pnpm install这是向 tsconfig 写入子包别名，一定要执行。后面每新增一个内嵌子目录都需要运行一次
# 修改tsconfig,将子包的别名写入paths中
pnpm update:tsconfigpnpm dev- 运行完成之后在浏览器访问
http://localhost:9100即可
# 从上游拉取 subtree 更新（需 SSH）
pnpm modules:update
# 打包
pnpm build| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| ❌ 子目录代码为空 | 使用了浅克隆或未拉全仓库 | 使用完整 clone，勿 --depth 1（除非你知道影响） |
| ❌ Permission denied (publickey) | 执行 modules:update 时 SSH 未配置 |
按上方 “SSH 配置” 步骤操作 |
| ❌ pnpm install 报错 | Node 版本过低或缓存损坏 | 升级 Node 至 ≥18 |
| ❌ 启动时报模块找不到 | 目录缺失或路径错误 | 确认 src/modules/* 存在 |
| ❌ 初始化页面中，菜单初始化项显示 “系统初始化0个菜单” | 业务模块目录不完整 | 检查 src/modules 下各目录是否齐全 |
| ❌ 登录进去之后页面没有菜单 | 菜单未初始化成功 | 进入 "/init-home" 进行初始化菜单操作 |
- chrome: ^105
- edge: ^105
- Firefox: ^140