553 lines
20 KiB
Markdown
553 lines
20 KiB
Markdown
# qiweimanager 项目解析与使用说明
|
||
|
||
更新时间：2026-05-18
|
||
|
||
## 1. 当前环境与部署结果
|
||
|
||
本项目是一个 Windows 桌面端企业微信辅助管理工具，界面使用 Wails + Vue 3，主程序由 Go 编写，另有一个 `helper.exe` 辅助进程通过本地 HTTP 服务、DLL 调用和回调模板与企业微信交互。
|
||
|
||
本机环境已经部署并验证：
|
||
|
||
| 项目 | 当前状态 |
|
||
| --- | --- |
|
||
| Go | `go1.26.2 windows/amd64`，项目 `go.mod` 要求 `go 1.23` |
|
||
| Node.js | `v23.8.0` |
|
||
| npm | `10.9.2` |
|
||
| Wails CLI | `v2.10.2`，已安装在 `%USERPROFILE%\go\bin\wails.exe` |
|
||
| WebView2 | Wails Doctor 检测已安装，版本 `148.0.3967.70` |
|
||
| 前端依赖 | 已执行 `npm install`，依赖在 `frontend/node_modules` |
|
||
| 前端产物 | 已生成 `frontend/dist` |
|
||
| 主程序构建 | 已通过 `go build ./...` 和 `wails build` |
|
||
| 发布目录 | 已生成并补齐 `build/bin` |
|
||
|
||
当前可直接运行的发布目录：
|
||
|
||
```text
|
||
build/bin/
|
||
qiweimanager.exe
|
||
helper.exe
|
||
Helper_4.1.33.6009.dll
|
||
Loader_4.1.33.6009.dll
|
||
config/
|
||
config.json
|
||
client_status.json
|
||
requestdata/
|
||
*.json
|
||
eventdata/
|
||
*.json
|
||
```
|
||
|
||
推荐从 `build/bin/qiweimanager.exe` 启动；当前项目根目录的 `qiweimanager.exe` 也已同步为 Wails 正式构建版本，可以直接双击运行。根目录原本自带的旧 exe 已备份为 `qiweimanager.old-invalid-build.exe`。
|
||
|
||
## 2. 项目整体架构
|
||
|
||
```text
|
||
Wails 主程序 qiweimanager.exe
|
||
├─ 嵌入 frontend/dist，展示 Vue 桌面界面
|
||
├─ 读取/保存 config/config.json
|
||
├─ 管理日志和操作记录
|
||
├─ 启动同级目录 helper.exe
|
||
└─ 通过 http://localhost:<httpPort> 调用 helper
|
||
|
||
helper.exe
|
||
├─ 启动本地 HTTP REST 服务，默认端口 10001
|
||
├─ 加载 Helper_4.1.33.6009.dll 和 Loader_4.1.33.6009.dll
|
||
├─ 注入/连接企业微信 WXWork.exe
|
||
├─ 将请求模板 requestdata/*.json 转换成底层消息 type
|
||
├─ 将企业微信事件 eventdata/*.json 转换成回调格式
|
||
└─ 将事件回调到 config.json 中配置的 callbackUrl
|
||
```
|
||
|
||
主要运行链路：
|
||
|
||
1. 启动 `qiweimanager.exe`。
|
||
2. 主程序初始化日志、配置、WebView2，并启动 `helper.exe`。
|
||
3. `helper.exe` 加载 DLL，启动本地 HTTP 服务。
|
||
4. 前端调用 Wails 绑定方法，例如 `SendWxWorkData`、`GetCallbackConfig`。
|
||
5. 主程序把指令转发到 `helper.exe` 的 `/api/send-wxwork-data`。
|
||
6. `helper.exe` 根据消息类型调用 DLL 或转换模板。
|
||
7. 企业微信回调数据进入 `MyRecvCallback` 后，经 `eventdata` 模板转换，再按配置推送到第三方回调地址。
|
||
|
||
## 3. 目录和文件说明
|
||
|
||
| 路径 | 作用 |
|
||
| --- | --- |
|
||
| `main.go` | Wails 主入口。初始化日志、配置、WebView2、单实例锁，启动/关闭 `helper.exe`。 |
|
||
| `app.go` | 暴露给前端的 Wails 方法，包含配置保存、发送企微数据、系统内存、账号列表、操作记录等。 |
|
||
| `http_client.go` | 主程序访问 helper 本地 HTTP 服务的客户端。 |
|
||
| `operation_record.go` | 操作日志 JSON 文件读写、分页、清理。 |
|
||
| `go.mod` / `go.sum` | Go 模块依赖，核心依赖是 `github.com/wailsapp/wails/v2 v2.10.2`。 |
|
||
| `wails.json` | Wails 项目配置，定义前端安装、构建和开发命令。 |
|
||
| `build_helper.bat` | 构建 32 位 `helper.exe` 并复制 DLL 的脚本。脚本末尾有 `pause`，命令行自动化时可改用本文的 PowerShell 命令。 |
|
||
| `Helper_4.1.33.6009.dll` | 企业微信辅助 DLL，运行时必须与 `helper.exe` 同级。 |
|
||
| `Loader_4.1.33.6009.dll` | 企业微信 Loader DLL，运行时必须与 `helper.exe` 同级。 |
|
||
| `qiweimanager.exe` | 仓库自带的旧可执行文件。当前构建产物在 `build/bin/qiweimanager.exe`。 |
|
||
| `config/` | 主程序默认配置结构与仓库内初始 `config.json`。运行时会读取 exe 同级的 `config/config.json`。 |
|
||
| `logger/` | 日志器，按日期写入 `Log/YYYY-MM-DD/*.txt`，最大文件约 5 MB，定期清理旧日志。 |
|
||
| `helper/` | 辅助进程源码，负责 DLL 加载、HTTP 服务、企业微信注入、事件转换和回调。 |
|
||
| `helper/config/client_status.json` | 示例账号状态文件。发布时已复制到 `build/bin/config/client_status.json`。 |
|
||
| `requestdata/` | 第三方请求模板。文件名对应 `/api/third-party-request` 的 `type`。 |
|
||
| `eventdata/` | 企业微信事件转换模板。文件名对应企业微信回调原始 `type`。 |
|
||
| `frontend/` | Vue 3 + Vite + Element Plus 前端工程。 |
|
||
| `frontend/src/App.vue` | 主界面：登录、系统首页、企微账号、操作记录、回调配置。 |
|
||
| `frontend/src/components/LoginModal.vue` | 登录弹窗，调用远程登录接口并保存 token 到本地配置。 |
|
||
| `frontend/src/components/WxWorkAccount.vue` | 企微账号列表，读取 `client_status.json`，支持下线/删除。 |
|
||
| `frontend/src/components/OperationLogs.vue` | 操作日志列表，读取本地操作记录。 |
|
||
| `frontend/wailsjs/` | Wails 自动生成的 JS/TS 绑定文件，不要手动改。 |
|
||
| `frontend/clear_storage.html` | 清空浏览器 localStorage 的小工具页面。 |
|
||
| `frontend/css` / `frontend/js` | 早期静态资源目录；当前入口是 `frontend/src/main.js`。 |
|
||
| `build/` | Wails 构建资源和输出目录。当前发布文件在 `build/bin`。 |
|
||
| `Log/` | 构建/运行时生成的日志目录。正式运行时会在 exe 同级目录生成日志。 |
|
||
|
||
## 4. 首次运行
|
||
|
||
1. 进入发布目录：
|
||
|
||
```powershell
|
||
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master\build\bin"
|
||
```
|
||
|
||
2. 启动主程序：
|
||
|
||
```powershell
|
||
.\qiweimanager.exe
|
||
```
|
||
|
||
3. 登录界面会要求输入账号、密码、验证码，并勾选测试学习用途声明。登录接口在前端代码中为：
|
||
|
||
```text
|
||
https://crm.yelangjiang.com/admin-api/system/auth/work-pw-login
|
||
```
|
||
|
||
4. 登录成功后进入主界面，可使用：
|
||
|
||
| 页面 | 功能 |
|
||
| --- | --- |
|
||
| 系统首页 | 查看消息累计、系统占用、活跃账号，点击“启动企微”。 |
|
||
| 企微账号 | 查看 `config/client_status.json` 中的账号状态，支持下线/删除。 |
|
||
| 操作记录 | 展示最新操作日志。 |
|
||
| 回调配置 | 配置回调地址、文件上传地址、HTTP 端口、设备编码、回调开关、云授权开关。 |
|
||
|
||
注意：企业微信相关功能依赖本机安装 `WXWork.exe`，并依赖项目自带 DLL 与目标企业微信版本兼容。
|
||
|
||
## 5. 配置文件
|
||
|
||
运行时配置位于发布目录：
|
||
|
||
```text
|
||
build/bin/config/config.json
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `callbackConfig.callbackUrl` | helper 收到事件后推送到第三方系统的 HTTP 回调地址。 |
|
||
| `callbackConfig.callbackToken` | 登录后会写入 accessToken，也可作为第三方接口鉴权 token 使用。 |
|
||
| `callbackConfig.httpPort` | helper 本地 HTTP 服务端口，默认 `10001`。 |
|
||
| `callbackConfig.enableCallback` | 是否开启事件回调。 |
|
||
| `callbackConfig.enableCloudAuth` | 是否开启云管理端授权。 |
|
||
| `callbackConfig.fileUploadUrl` | 媒体/文件上传地址。 |
|
||
| `callbackConfig.deviceCode` | 设备编码。 |
|
||
| `lastUpdated` | 最后保存时间戳。 |
|
||
|
||
账号状态文件：
|
||
|
||
```text
|
||
build/bin/config/client_status.json
|
||
```
|
||
|
||
它保存企业微信账号信息和在线状态，`GetWxWorkAccountList`、`DeleteWxWorkAccount`、机器人列表接口都会读取该文件。
|
||
|
||
## 6. 本地 HTTP API
|
||
|
||
helper 启动后默认监听：
|
||
|
||
```text
|
||
http://localhost:10001
|
||
```
|
||
|
||
如果修改了 `config.json` 的 `httpPort`，端口会随之变化。
|
||
|
||
### 健康检查
|
||
|
||
```powershell
|
||
Invoke-RestMethod "http://localhost:10001/api/health"
|
||
```
|
||
|
||
成功时返回：
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"time": "2026-05-18 15:00:00"
|
||
}
|
||
```
|
||
|
||
### 直接发送企业微信底层指令
|
||
|
||
接口：
|
||
|
||
```text
|
||
POST /api/send-wxwork-data
|
||
```
|
||
|
||
示例：
|
||
|
||
```json
|
||
{
|
||
"clientId": "1688858204634393",
|
||
"data": {
|
||
"type": 11029,
|
||
"data": {
|
||
"conversation_id": "S:xxx",
|
||
"content": "hello"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
`data` 可以是 JSON 对象，也可以是 JSON 字符串。部分类型会直接返回结果，部分类型会等待企业微信回调，超时时间约 10 秒。
|
||
|
||
特殊类型：
|
||
|
||
| type | 说明 |
|
||
| --- | --- |
|
||
| `10000` | 启动/注入企业微信。前端“启动企微”按钮使用该类型。 |
|
||
| `10002` | 获取当前活跃客户端数量。 |
|
||
| `10003` | 获取机器人列表，来自 `getVWorkAccountListRequest.json`。 |
|
||
| `11036` | 在主程序里也被用于操作日志分页读取；在模板中也表示获取内部好友列表，注意调用上下文。 |
|
||
| `99999` | 主程序调试类型，用于测试操作日志读取。 |
|
||
|
||
### 第三方请求模板接口
|
||
|
||
接口：
|
||
|
||
```text
|
||
POST /api/third-party-request
|
||
```
|
||
|
||
第三方只需要传模板名称和参数，helper 会从 `requestdata/<type>.json` 找模板并替换 `{{params.xxx}}`。
|
||
|
||
示例：发送文本消息
|
||
|
||
```json
|
||
{
|
||
"type": "sendVWorkTextMessage",
|
||
"params": {
|
||
"robotId": "1688858204634393",
|
||
"conversationId": "S:1688xxxx_1688xxxx",
|
||
"message": "hello"
|
||
}
|
||
}
|
||
```
|
||
|
||
模板文件一般包含两个 JSON 对象：
|
||
|
||
1. 第一个对象是第三方请求格式说明。
|
||
2. 第二个对象是转换后的企业微信底层请求。
|
||
|
||
## 7. Wails 前端绑定方法
|
||
|
||
Wails 生成的前端绑定在：
|
||
|
||
```text
|
||
frontend/wailsjs/go/main/App.js
|
||
```
|
||
|
||
当前可从前端调用的方法：
|
||
|
||
| 方法 | 作用 |
|
||
| --- | --- |
|
||
| `AddLogEntry(source, type, content, duration)` | 写入一条操作日志。 |
|
||
| `DebugLoadLogEntries()` | 加载当天最新操作日志，主要供操作记录页面使用。 |
|
||
| `DeleteWxWorkAccount(userId)` | 从 `client_status.json` 删除账号。 |
|
||
| `GetActiveClientCount()` | 查询 helper 当前活跃客户端数量。 |
|
||
| `GetCallbackConfig()` | 获取当前配置。 |
|
||
| `GetSystemMemoryUsage()` | 获取 Windows 系统内存使用率。 |
|
||
| `GetWxWorkAccountList()` | 读取企微账号列表。 |
|
||
| `Greet(name)` | Wails 模板保留的示例方法。 |
|
||
| `LogFrontend(level, message)` | 前端日志写入 Go 日志文件。 |
|
||
| `SaveCallbackConfig(jsonData)` | 保存回调配置。 |
|
||
| `SendWxWorkData(clientId, jsonData)` | 发送企业微信底层指令到 helper。 |
|
||
|
||
## 8. requestdata 模板清单
|
||
|
||
`requestdata` 目录共 44 个模板。第三方调用 `/api/third-party-request` 时，`type` 填第二列名称。
|
||
|
||
| 文件 | 第三方 type | 底层 type |
|
||
| --- | --- | --- |
|
||
| `addVWorkCardUser.json` | `addVWorkCardUser` | `11121` |
|
||
| `addVWorkDeletedUser.json` | `addVWorkDeletedUser` | `11152` |
|
||
| `addVWorkFriendRequestFromGroup.json` | `addVWorkFriendRequestFromGroup` | `11071` |
|
||
| `addVWorkSearchUser.json` | `addVWorkSearchUser` | `11053` |
|
||
| `addVWorkSearchVWorkUser.json` | `addVWorkSearchVWorkUser` | `11088` |
|
||
| `agreeVWorkUser.json` | `agreeVWorkUser` | `11064` |
|
||
| `c2cCdnDown.json` | `c2cCdnDown` | `11170` |
|
||
| `c2cCdnUpload.json` | `c2cCdnUpload` | `11115` |
|
||
| `changeVWorkGroupNameRequest.json` | `changeVWorkGroupNameRequest` | `11059` |
|
||
| `changeVWorkUserCompany.json` | `changeVWorkUserCompany` | `11057` |
|
||
| `changeVWorkUserDesc.json` | `changeVWorkUserDesc` | `11055` |
|
||
| `changeVWorkUserPhone.json` | `changeVWorkUserPhone` | `11056` |
|
||
| `changeVWorkUserRemark.json` | `changeVWorkUserRemark` | `11054` |
|
||
| `createVWorkEmptyGroupRequest.json` | `createVWorkEmptyGroupRequest` | `11125` |
|
||
| `createVWorkGroupRequest.json` | `createVWorkGroupRequest` | `11058` |
|
||
| `deleteVWorkUser.json` | `deleteVWorkUser` | `11111` |
|
||
| `delVWorkMembersRequest.json` | `delVWorkMembersRequest` | `11061` |
|
||
| `dissolveGroupVWork.json` | `dissolveGroupVWork` | `11130` |
|
||
| `getCurrentAccountInfo.json` | `getCurrentAccountInfo` | `11035` |
|
||
| `getVWorkAccountListRequest.json` | `getVWorkAccountListRequest` | `10003` |
|
||
| `getVWorkExternalFriendList.json` | `getVWorkExternalFriendList` | `11037` |
|
||
| `getVWorkFriendInfo.json` | `getVWorkFriendInfo` | `11039` |
|
||
| `getVWorkGroupList.json` | `getVWorkGroupList` | `11038` |
|
||
| `getVWorkGroupMemberList.json` | `getVWorkGroupMemberList` | `11040` |
|
||
| `getVWorkInternalFriendList.json` | `getVWorkInternalFriendList` | `11036` |
|
||
| `groupInvitationVWorkConfirmationStatus.json` | `groupInvitationVWorkConfirmationStatus` | `11089` |
|
||
| `groupNameVWorkChangeStatus.json` | `groupNameVWorkChangeStatus` | `11108` |
|
||
| `inviteVWorkMembersRequest.json` | `inviteVWorkMembersRequest` | `11060` |
|
||
| `pushVWorkGroupNotice.json` | `pushVWorkGroupNotice` | `11082` |
|
||
| `quitGroupVWork.json` | `quitGroupVWork` | `11105` |
|
||
| `searchVWorkUserInfo.json` | `searchVWorkUserInfo` | `11052` |
|
||
| `sendVWorkAppletMessage.json` | `sendVWorkAppletMessage` | `11162` |
|
||
| `sendVWorkCardMessage.json` | `sendVWorkCardMessage` | `11161` |
|
||
| `sendVWorkFileMessage.json` | `sendVWorkFileMessage` | `11031` |
|
||
| `sendVWorkGifMessage.json` | `sendVWorkGifMessage` | `11070` |
|
||
| `sendVWorkGroupAtMessage.json` | `sendVWorkGroupAtMessage` | `11069` |
|
||
| `sendVWorkImageMessage.json` | `sendVWorkImageMessage` | `11030` |
|
||
| `sendVWorkTextMessage.json` | `sendVWorkTextMessage` | `11029` |
|
||
| `sendVWorkUrlMessage.json` | `sendVWorkUrlMessage` | `11159` |
|
||
| `sendVWorkVideoMessage.json` | `sendVWorkVideoMessage` | `11067` |
|
||
| `sendVWorkVideoNumberLiveMessage.json` | `sendVWorkVideoNumberLiveMessage` | `11196` |
|
||
| `sendVWorkVideoNumberMessage.json` | `sendVWorkVideoNumberMessage` | `11172` |
|
||
| `transferVWorkGroupOwner.json` | `transferVWorkGroupOwner` | `11090` |
|
||
| `wxCdnDown.json` | `wxCdnDown` | `11171` |
|
||
|
||
## 9. eventdata 事件模板清单
|
||
|
||
`eventdata` 目录共 28 个模板。helper 接收企业微信原始事件后，会按原始 `type` 找同名文件进行转换。
|
||
|
||
| 文件 | 原始 type | 回调 event | 描述 |
|
||
| --- | --- | --- | --- |
|
||
| `11026.json` | `11026` | `20001` | 用户登录成功通知事件 |
|
||
| `11027.json` | `11027` | `20009` | 用户退出通知事件 |
|
||
| `11028.json` | `11028` | `20025` | 登录二维码通知事件 |
|
||
| `11041.json` | `11041` | `20002` | 文本消息事件 |
|
||
| `11042.json` | `11042` | `20003` | 图片消息事件 |
|
||
| `11043.json` | `11043` | `20004` | 视频消息事件 |
|
||
| `11044.json` | `11044` | `20012` | 语音消息事件 |
|
||
| `11045.json` | `11045` | `20005` | 文件消息事件 |
|
||
| `11046.json` | `11046` | `20013` | 位置消息事件 |
|
||
| `11047.json` | `11047` | `20007` | 链接消息事件 |
|
||
| `11048.json` | `11048` | `20006` | 表情消息事件 |
|
||
| `11049.json` | `11049` | `20011` | 红包消息事件 |
|
||
| `11050.json` | `11050` | `20008` | 名片消息事件 |
|
||
| `11063.json` | `11063` | `20017` | 好友申请通知事件 |
|
||
| `11066.json` | `11066` | `20059` | 小程序消息事件 |
|
||
| `11068.json` | `11068` | `20014` | 图文消息事件 |
|
||
| `11072.json` | `11072` | `20030` | 新增群成员通知事件 |
|
||
| `11073.json` | `11073` | `20022` | 群成员减少通知事件 |
|
||
| `11074.json` | `11074` | `20020` | 新增群通知事件 |
|
||
| `11075.json` | `11075` | `20023` | 主动退群通知事件 |
|
||
| `11076.json` | `11076` | `20027` | 好友新增通知事件 |
|
||
| `11077.json` | `11077` | `20018` | 好友删除通知事件 |
|
||
| `11078.json` | `11078` | `20024` | 群名称变化通知事件 |
|
||
| `11123.json` | `11123` | `20015` | 撤回消息事件 |
|
||
| `11124.json` | `11124` | `20010` | 视频号消息事件 |
|
||
| `11173.json` | `11173` | `20019` | 被删除通知事件 |
|
||
| `11174.json` | `11174` | `20026` | 登录二维码状态通知事件 |
|
||
| `11195.json` | `11195` | `20016` | 视频号直播消息事件 |
|
||
|
||
## 10. 开发环境启动
|
||
|
||
PowerShell 当前执行策略会拦截 `npm.ps1`，所以建议用 `cmd /c npm ...` 或 `npm.cmd ...`。
|
||
|
||
前端单独开发：
|
||
|
||
```powershell
|
||
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master\frontend"
|
||
cmd /c npm install --cache .npm-cache
|
||
cmd /c npm run dev
|
||
```
|
||
|
||
Wails 开发模式：
|
||
|
||
```powershell
|
||
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master"
|
||
& "$env:USERPROFILE\go\bin\wails.exe" dev
|
||
```
|
||
|
||
如果希望直接使用 `wails` 命令，把下面路径加入用户 PATH：
|
||
|
||
```text
|
||
%USERPROFILE%\go\bin
|
||
```
|
||
|
||
## 11. 重新构建发布包
|
||
|
||
完整发布建议按下面顺序执行。
|
||
|
||
### 1. 构建前端
|
||
|
||
```powershell
|
||
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master\frontend"
|
||
cmd /c npm install --cache .npm-cache
|
||
cmd /c npm run build
|
||
```
|
||
|
||
### 2. 构建 Wails 主程序
|
||
|
||
```powershell
|
||
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master"
|
||
& "$env:USERPROFILE\go\bin\wails.exe" build
|
||
```
|
||
|
||
成功后主程序位于：
|
||
|
||
```text
|
||
build/bin/qiweimanager.exe
|
||
```
|
||
|
||
### 3. 构建 helper.exe
|
||
|
||
```powershell
|
||
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master\helper"
|
||
$env:GOARCH='386'
|
||
go build -ldflags='-H windowsgui -s -w' -o ..\build\bin\helper.exe .
|
||
Remove-Item Env:GOARCH
|
||
```
|
||
|
||
### 4. 复制运行时资源
|
||
|
||
```powershell
|
||
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master"
|
||
New-Item -ItemType Directory -Force -Path build\bin\config, build\bin\requestdata, build\bin\eventdata
|
||
Copy-Item -Force Helper_4.1.33.6009.dll build\bin\Helper_4.1.33.6009.dll
|
||
Copy-Item -Force Loader_4.1.33.6009.dll build\bin\Loader_4.1.33.6009.dll
|
||
Copy-Item -Force config\config.json build\bin\config\config.json
|
||
Copy-Item -Force helper\config\client_status.json build\bin\config\client_status.json
|
||
Copy-Item -Recurse -Force requestdata\* build\bin\requestdata\
|
||
Copy-Item -Recurse -Force eventdata\* build\bin\eventdata\
|
||
```
|
||
|
||
最终把整个 `build/bin` 目录作为发布包使用。
|
||
|
||
## 12. 已做的修正
|
||
|
||
本次环境部署中修正了一个前端构建问题：
|
||
|
||
| 文件 | 修正 |
|
||
| --- | --- |
|
||
| `frontend/vite.config.js` | 将 `@` 别名从 `'/src'` 改为基于 `import.meta.url` 的 `frontend/src` 绝对路径，避免 Windows/esbuild 在沙箱或受限目录下错误访问磁盘根目录。 |
|
||
|
||
如果不做该修正，`npm run build` 会报：
|
||
|
||
```text
|
||
Cannot read directory "../../../..": Access is denied.
|
||
```
|
||
|
||
## 13. 验证记录
|
||
|
||
已经通过的验证命令：
|
||
|
||
```powershell
|
||
go list ./...
|
||
go build ./...
|
||
cmd /c npm run build
|
||
& "$env:USERPROFILE\go\bin\wails.exe" doctor
|
||
& "$env:USERPROFILE\go\bin\wails.exe" build
|
||
```
|
||
|
||
验证结果：
|
||
|
||
| 项目 | 结果 |
|
||
| --- | --- |
|
||
| Go 包解析 | 通过，识别 `qiweimanager`、`qiweimanager/config`、`qiweimanager/helper`、`qiweimanager/logger`。 |
|
||
| Go 编译 | 通过。 |
|
||
| Vite 构建 | 通过，生成 `frontend/dist`。有 chunk 超过 500 KiB 的提醒，不影响运行。 |
|
||
| Wails Doctor | 通过，系统可用于 Wails 开发。 |
|
||
| Wails Build | 通过，生成 `build/bin/qiweimanager.exe`。 |
|
||
| helper 构建 | 通过，生成 `build/bin/helper.exe`。 |
|
||
| 发布资源 | 已复制 DLL、配置、请求模板、事件模板到 `build/bin`。 |
|
||
|
||
## 14. 常见问题
|
||
|
||
### PowerShell 执行 `npm` 被拦截
|
||
|
||
现象：
|
||
|
||
```text
|
||
npm.ps1，因为在此系统上禁止运行脚本
|
||
```
|
||
|
||
处理方式：
|
||
|
||
```powershell
|
||
cmd /c npm -v
|
||
cmd /c npm install
|
||
cmd /c npm run build
|
||
```
|
||
|
||
### `wails` 命令找不到
|
||
|
||
Wails 已安装，但可能不在 PATH。使用完整路径：
|
||
|
||
```powershell
|
||
& "$env:USERPROFILE\go\bin\wails.exe" version
|
||
```
|
||
|
||
或者把 `%USERPROFILE%\go\bin` 加入 PATH。
|
||
|
||
### 启动后 helper 无法工作
|
||
|
||
检查 `qiweimanager.exe` 同级是否有：
|
||
|
||
```text
|
||
helper.exe
|
||
Helper_4.1.33.6009.dll
|
||
Loader_4.1.33.6009.dll
|
||
config/config.json
|
||
config/client_status.json
|
||
requestdata/
|
||
eventdata/
|
||
```
|
||
|
||
还要确认企业微信 `WXWork.exe` 已安装，DLL 与企业微信版本兼容。
|
||
|
||
### 本地 HTTP 接口不通
|
||
|
||
检查 `config/config.json` 中的端口：
|
||
|
||
```json
|
||
{
|
||
"callbackConfig": {
|
||
"httpPort": "10001"
|
||
}
|
||
}
|
||
```
|
||
|
||
然后测试：
|
||
|
||
```powershell
|
||
Invoke-RestMethod "http://localhost:10001/api/health"
|
||
```
|
||
|
||
如果端口被占用，改 `httpPort` 后重启应用。
|
||
|
||
### 语音消息转换失败
|
||
|
||
`helper/client_id_handler.go` 中语音转换会查找 `ffmpeg`。处理方式：
|
||
|
||
1. 将 `ffmpeg.exe` 放到 `build/bin`。
|
||
2. 或者把 ffmpeg 加入系统 PATH。
|
||
|
||
### 日志在哪里
|
||
|
||
正式运行后通常在 exe 同级目录生成：
|
||
|
||
```text
|
||
Log/YYYY-MM-DD/*.txt
|
||
operations/YYYY-MM-DD_operations.json
|
||
```
|
||
|
||
主程序日志、前端日志、helper 日志、操作记录都会写入本地文件，排查问题优先看这些目录。
|