Project Map · Dependencies
分两层：功能靠什么才能跑（账号、服务、平台、前置操作）， 以及代码装了哪些包、哪些能动哪些不能。
gameboxclient 工作区快照。 「是否被引用」是当时用 grep
逐个包核过的，含 extend/worker/ 里的纯 Node 脚本。
问「这个项目有哪些依赖」，通常回答的是 package.json 里那 121
个包。 但你接手后真正会被绊住的，八成不是包的问题。
真正会绊住你的是这种事：改完一条 NPC 配置点保存，报错； 你以为是代码写错了，查半天才发现是当时选的服务器不对。 或者点发布毫无反应，最后发现是登录接口没给你下发 Jenkins token。
这类「A 功能要先有 B、还要有某个账号、还只能在 Windows 上跑」的关系， 在代码里到处散落，没有任何一处集中写着。所以这一页把它放在最前面。
这张图最该记住的是那个根节点。
排查任何「点了没反应」的问题，第一步不是看功能代码，
是确认登录有没有真的成功、以及
/user/info 有没有下发该给的配置。
「缺了会怎样」这一列是排障时最有用的 —— 大部分缺失都不会弹错误，只是安静地什么都不发生。
| 功能 | 前置功能 | 要账号 / 凭据 | 要外部服务 | 平台 | 缺了会怎样 |
|---|---|---|---|---|---|
| 登录 | — | GameBox 账号密码 | 用户中心 /user/login + /user/info |
任意 | 停在登录页，守卫把所有路由打回 /login |
| 任何业务页 | 登录 | 会话 token | — | 任意 | 重定向回登录页并带 ?redirect= |
| 字段表单渲染 | 登录 + table store 初始化 |
— | — | 任意 | schema 为空 → 表单渲染成空白。注意 init 在登录后延迟 1500ms 才跑， 这期间进编辑页可能拿到空 config |
| 配置表编辑 | 登录 + 选服 | pcode（登录下发，选服时会改写） | GM 接口 /1000y/engine/cmd |
任意 |
请求打到错的服，或 excelToken 校验不过 →
数据空白或报错
|
| 表编辑（Excel） | 登录 + 选服 | 同上 | 同上 | 任意 | 同上；另外从 /expert/* 跳进来会先弹确认框 |
| Excel 独立小窗 | 先打开表编辑页 | 会话数据经 IPC 传入 | — | 任意 |
会话没传过去 → 小窗停在空白或被守卫踢回； 小窗里的路由被
docView() 单独管制
|
| GM 工具 | 登录 + 选服 | VITE_API_GM_PCODE（选服时按版本计算） |
GM 接口 | 任意 | 没选服时该键是空串 → 请求带不上 pcode，服务端拒绝 |
| 错误日志 / 脚本管理 / 全局数据 | 登录 + 选服 | 各自独立的 pcode 键 | GM 接口 | 任意 |
这三个各用一套 pcode（GM / SCRIPT /
SECTCONFIG），互相不通用
|
| 发布 · Jenkins 型 | 登录 + 当前没有别的构建在跑 | Jenkins url / account / token（登录下发） | Jenkins 服务器 + 对应 job 存在 | 任意 | 凭据缺失 → Jenkins 客户端根本没被创建，点了静默无反应； job 不存在 → 轮询永远等不到结果 |
| 发布 · SVN 型 | 登录 + 同上闸门 + 本地已有工作副本 | SVN url / 账号 / 密码（登录下发） | SVN 仓库可达 | 需要可执行的 svn 二进制 |
Mac arm64 上
extend/Svn/Mac/Arm64/1.14.2/bin/svn 没有可执行位 →
exec 直接失败
|
| 资源下载 / 解压 | 登录 | 资源地址（多由接口下发） | 资源服务器 | 任意 | 主进程 fork 子进程干活，进度经 IPC 回传； 子进程崩了界面上的进度条会停住不动 |
| 文件上传 / 下载（COS） | 登录 | COS SecretId / SecretKey | 腾讯云 COS | 任意 |
COS_Handler.init() 内部
try/catch 吞掉异常并 return false ——
初始化失败完全没有提示
|
| 地图转换 / 动画转换 | 登录 | — | — | 仅 Windows |
调
extend/Python/**/*.exe；而且解释器路径当前指向不存在的目录，
所有平台都跑不通（见下方红框）
|
| 本地预览（nginx） | 登录成功时自动拉起 | — | — | 仅 Windows |
ReLogin/index.vue:256 的 initNginx() 跑
initNginx.exe；Mac 上失败但不影响登录本身
|
| 7-Zip 压缩 | — | — | — | 仅 Windows |
代码里写死 ./7zip-bin/win/7za.exe
（Animation/security.ts:280,334）
|
❌ 别学
凭据缺失一律静默失败。
src/utils/extend/jenkins/index.ts 里所有导出函数都写成
_buildService?.start(...) 这种可选链形式 ——
客户端没初始化时表达式求值为 undefined，函数正常返回，
没有任何异常、没有任何日志。
COS_Handler.init() 同理：catch 里直接
return false，没人检查这个返回值。
规范做法是「快速失败」：初始化时凭据不全就抛， 或至少在 UI 上标出「Jenkins 未连接」，让用户知道点了也没用。
你现在能做的：把
JSON.parse(localStorage.getItem('GameENV'))
当成排障第一条命令。这一条能省掉你未来几十次的无效排查。
❌ 别学
Python 工具链的解释器路径指向不存在的目录。
src/utils/extend/python.ts:34-41 按平台拼解释器路径：
Windows 用 extend/Python/Win/3.11/python.exe， Mac arm64 用
extend/Python/Mac/3.8/bin/python3。 但当前
extend/Python/ 下这两个目录都不存在 ——
实际只有 move/ luaTrans/ Script/ mapMask/ transPlist/，
里面是 16 个 .exe 和 3 个 .py。
合理的猜测是：这些脚本已经被 PyInstaller 之类打包成独立
exe，不再需要外部解释器，而 python.ts 里的 command
拼接是遗留代码。 但这只是猜测，没有证据。
这是你上手后最该优先问清楚的技术问题之一。 在拿到答案前不要自己改路径 —— 你可能只是把一个「明显坏掉」变成「悄悄坏掉」。
package.json 里
62 个运行时依赖 + 59 个开发依赖。
下面按用途分组，重点标出能不能升级和是不是真的在用。
| 包 | 版本 | 干什么 | 能不能动 |
|---|---|---|---|
vue |
^3.3.4 | 渲染层框架 | ⚠️ 小版本可升，大版本没有 |
vite |
4.1.4（精确锁定，无 ^） | 构建工具 |
❌ 锁死。和 vite-plugin-electron@0.11、
rollup@3 是一套，动一个全炸
|
typescript |
4.9.5（精确锁定） | 类型检查 |
❌ 锁死。升级会让 vue-tsc 现有的错误数量剧变，
而验收标准是「不新增错误」
|
electron |
^21.4.4 | 桌面运行时 |
❌ 别动。这是2022 年的版本， 升级会连带影响
@electron/remote、
nodeIntegration 行为和打包配置
|
electron-builder |
^23.6.0 | 打包分发 | ❌ 与 electron 版本绑定 |
pinia |
^2.1.6 | 状态管理（22 个文件在用） | ⚠️ 可升 2.x，Pinia 3 需要 Vue 3.4+ |
vue-router |
^4.2.5 | 路由（hash 模式） | ✅ 相对安全 |
element-plus |
^2.14.3 | UI 组件库，204 个文件在用 | ⚠️ 用得太深，升级要全量回归 |
@intlify/unplugin-vue-i18n |
^0.8.2 | i18n 构建插件 |
❌ 别动。git 历史里有一次专门的
fix(deps): 锁定 @intlify 版本…修复项目无法启动
|
vite-plugin-style-import |
2.0.0（精确锁定） | Element Plus 样式按需引入 | ❌ 锁死 |
| 用途 | 包 | 说明 |
|---|---|---|
| 网络 | axios · qs |
只在 src/config/axios/ 里封装，业务层不直接用 |
| 加密 |
crypto-js · js-sha256 ·
js-base64
|
登录密码摘要与 excelToken 生成 |
| Electron 生态 |
@electron/remote · electron-log ·
electron-updater
|
electron-log
是主进程日志的唯一出口，排障必看
|
| 外部工具 | node-svn-ultimate · jenkins |
各 2 个文件在用，都在 src/utils/extend/ 下 |
| 对象存储 |
cos-js-sdk-v5（腾讯） · ali-oss（阿里）
|
两套并存，各 1 个文件在用。COS 是主力，OSS 疑似历史遗留 |
| 压缩归档 |
adm-zip · archiver ·
jszip · unzipper ·
unzip-stream · 7zip-min ·
yauzl
|
七个压缩库。yauzl 只被
extend/worker/ 的子进程脚本用， 别因为 src/
里搜不到就删掉
|
| 表格 / Excel |
xlsx（3 处） · x-data-spreadsheet（2
处）
|
专家模式的表编辑功能 |
| 图形 |
konva（地图编辑画布） · fabric ·
ol / OpenLayers（Map/components/mapLoad2.vue
等）
|
三套画布库并存，各管一块，改地图相关功能前先确认在哪一套上 |
| 新手引导 |
intro.js（3 处） · shepherd.js（1 处）
|
两套引导库并存 |
| 文件系统 |
fs-extra（13 处，用得最多） · rimraf（4
处） ·
image-size
|
渲染层直接用 Node fs，这是 nodeIntegration 的直接后果
|
| 工具库 |
lodash +
lodash-es（两个都装了） ·
moment · mitt ·
web-storage-cache ·
nprogress
|
moment 已停止维护，新代码建议用原生
Intl.DateTimeFormat
|
下面这些在 dependencies 里，但 src/、
electron/、extend/worker/ 三处
全文搜不到任何引用。它们仍然会被打进安装包，白白增加体积。
| 包 | 本来是干什么的 | 处置建议 |
|---|---|---|
mockjs |
接口 mock |
✅ 可删。vite-plugin-mock 也在 devDeps 里但
vite.config.ts 没启用
|
vue-audio-player +
@liripeng/vue-audio-player
|
音频播放，装了两个 | ✅ 两个都可删 |
@esotericsoftware/spine-player |
Spine 骨骼动画播放 | ⚠️ 动画模块有 6038 行，先确认是不是通过别的方式加载（比如全局 script） |
vxe-table · xe-utils |
表格组件 | ✅ 疑似被 Element Plus 表格取代 |
node-xlsx |
Excel 读写（xlsx 已经在用了） |
✅ 可删 |
ncp · execa |
文件复制 / 进程执行 |
✅ 已被原生 fs-extra 和
child_process 取代
|
html2canvas |
DOM 截图 | ✅ 可删 |
vue3-menus |
右键菜单 | ✅ 可删 |
electron-store |
主进程持久化配置 | ✅ 可删。配置目前全走 localStorage —— 这也是凭据明文落盘的根因 |
@iconify/iconify · iconv-lite |
图标运行时 / 编码转换 | ⚠️ 可能被构建插件间接使用，删前先跑一次完整构建 |
7zip-bin |
7-Zip 二进制 |
⚠️ npm 包没被 import，代码直接走
extend/7zip-bin/win/7za.exe 这个路径。 npm
包看起来是冗余的，但确认前别删
|
electron-icon-builder |
生成应用图标 |
⚠️ 是 npm run electron:generate-icons 的工具，
应该在 devDependencies 里，现在在 dependencies
|
删包之前
本项目大量使用动态 require() 和路径拼接，静态搜索会漏。
安全的做法是：删一个 → npm run build:pro 跑通 →
npm run ts:check 错误数不增 → 真机走一遍主流程。
一次只删一个，别批量。
❌ 别学
stylelint 同时出现在 dependencies 和
devDependencies 里，而且版本范围不同
（^15.11.0 vs ^15.10.3）。
stylelint-config-prettier 同样两边都有， 且
dependencies 里写的是 "latest"。
后果：lint 工具被打进生产包；
"latest" 意味着不同时间装出来的依赖树可能不一样，
「我这能跑你那不能跑」的经典成因。
规范做法：lint / 构建工具一律进
devDependencies， 版本一律用确定的范围，永远不写
latest。
这条改动风险低、收益明确，适合作为你的第一个正式提交。
❌ 别学
.npmrc 在当前工作区里不存在了。
git 历史里有一次提交
chore(npm): .npmrc 增加 legacy-peer-deps，让裸 npm i 也能装上， 但新版本把它删掉了。
后果：直接跑 npm i 会因为 peer dependency
冲突失败。 必须跑 npm i --legacy-peer-deps，或者用
package.json 里已有的 npm run i （它等于
npm i --legacy-peer-deps && npm run cpsvn）。
建议：把
.npmrc 加回去。这是新人上手的第一道坎， 没人会想到去翻
package.json 里那个只有一个字母的脚本名。
⚠️ 隔离
Node 版本没有任何约束文件。
package.json 的 engines 写着
node >= 14.18.0，但
devDependencies 里又装了一个
"node": "^22.13.0"（把 node 本身当 npm 包装，
这个写法本身就很可疑），而仓库里没有 .nvmrc 也没有 .node-version。
后果：每个人用的 Node 版本都不一样， 原生模块（node-svn-ultimate
之类）编译结果也就不一样。 「别人能跑我不能跑」优先怀疑这里。
规范做法：加一个 .nvmrc， 写死团队统一的
Node 大版本，并让 engines 与之一致。
package.json 里
"prepare": "husky install" 和
"lint:lint-staged": "lint-staged -c ./.husky/lintstagedrc.js"
都指向 .husky/，但这个目录在当前工作区里已经不存在
—— 提交钩子实际上是失效的。
extend/
这些不走 npm，是直接放在仓库里、随安装包分发的可执行文件。
electron-builder.json5 的 files 里显式包含了
extend，并在 asarUnpack 里解包，
这样运行时才能用真实路径调用它们。
| 目录 | 是什么 | 谁在用 | 状态 |
|---|---|---|---|
extend/worker/ |
6 个纯 Node 脚本：download / decompress / unzip / spwandownload / spwanUnZip / spwanUnZip7Z | 主进程 fork 出来跑 |
✅ 是 JS，能读能改。唯一一处你能轻松改的「外部工具」 |
extend/Svn/ |
便携版 SVN 客户端，分 Mac/ 和 Win/
|
src/utils/extend/svn.ts |
❌ Mac arm64
的二进制没有可执行位（-rw-r--r--），
SVN 链路在 Mac 上直接失败
|
extend/Python/ |
16 个 .exe + 3 个 .py |
src/utils/extend/python.ts |
❌ 代码要找的 Win/3.11/ 和 Mac/3.8/
两个目录都不存在
|
extend/map/ · extend/TiledMap/ |
地图资源生成与编辑工具（exe） | 地图模块 | ⚠️ 仅 Windows |
extend/QNnginx/ · extend/QNnode/ |
便携版 nginx 和 node | 登录时 initNginx() 拉起，做本地资源预览 |
⚠️ 仅 Windows（nginx.exe / node.exe）
|
extend/7zip-bin/ |
7-Zip | Animation/security.ts |
⚠️ 只有 win/ 目录，没有 Mac 版
|
extend/config/ ·
extend/localTableHeader/ ·
extend/delData/ · extend/files/
|
随包分发的 JSON 配置与素材 | 运行时读取 |
✅ 纯数据。localTableHeader/ 按渠道名取文件，
渠道对不上会静默读取失败
|
结论：这是一个 Windows 优先的工具
把上面几行连起来看：SVN 二进制、Python exe、地图工具、nginx、node、7-Zip —— 可执行的外部工具几乎全是 Windows 版。
在 macOS 上你能做的是：跑起来、登录、改配置表、看代码、做定位。 做不了的是：SVN 提交、地图/动画转换、本地预览、打正式包。
所以「要不要申请一台 Windows 机器」不是偏好问题， 是能不能完整履行这个岗位职责的问题。 这条应该写进你的第一周汇报。