From 2f2f682fa0f4d57a332fee7b9faa84abc2e795d1 Mon Sep 17 00:00:00 2001
From: wushili <969149642@qq.com>
Date: Tue, 11 Aug 2026 11:23:29 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E6=9C=AC=E5=9C=B0?=
 =?UTF-8?q?=E5=90=AF=E5=8A=A8=E6=8E=92=E9=9A=9C=E6=96=87=E6=A1=A3=20&=20?=
 =?UTF-8?q?=E6=B7=BB=E5=8A=A0electron=E4=B8=8B=E8=BD=BD=E6=BA=90=E9=85=8D?=
 =?UTF-8?q?=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .npmrc                                        |  1 +
 docs/README.md                                |  1 +
 .../local-startup-troubleshooting.md          | 62 +++++++++++++++++++
 docs/development/overview.md                  |  2 +
 4 files changed, 66 insertions(+)
 create mode 100644 docs/development/local-startup-troubleshooting.md

diff --git a/.npmrc b/.npmrc
index bf2e764..4b5e155 100644
--- a/.npmrc
+++ b/.npmrc
@@ -1 +1,2 @@
 shamefully-hoist=true
+electron_mirror=https://npmmirror.com/mirrors/electron/
diff --git a/docs/README.md b/docs/README.md
index fc8747c..5c7db51 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -55,6 +55,7 @@ WechatExplorer 有两种不同的接入方式。微信机器人是普通用户
 
 - [macOS 数据访问说明](./platform/macos.md)
 - [开发、测试与构建](./development/overview.md)
+- [本地启动排障](./development/local-startup-troubleshooting.md)
 - [v2.1.9 API 鉴权迁移说明](./agent/release-notes-v2.1.9.md)
 
 当前工作区版本：**2.1.9**。文档只描述当前代码已经实现的能力；版本兼容性、AI Provider 行为和媒体读取结果可能随系统、微信客户端和服务商变化。
diff --git a/docs/development/local-startup-troubleshooting.md b/docs/development/local-startup-troubleshooting.md
new file mode 100644
index 0000000..db1cd70
--- /dev/null
+++ b/docs/development/local-startup-troubleshooting.md
@@ -0,0 +1,62 @@
+# 本地启动排障
+
+本文面向运行源码开发环境的贡献者。常规启动顺序和测试入口请先阅读[开发、测试与构建](./overview.md)。
+
+## 启动成功的判断标准
+
+执行 `pnpm dev` 后，以下状态同时满足，说明本地开发环境已经可用：
+
+- 控制台显示连接器已生成，例如 `resources/connectors/wechat/win32-x64/wechat-connector.exe`；
+- Electron 窗口已打开，或 `http://localhost:5173/` 返回 HTTP `200`；
+- 控制台显示 Local HTTP API 正在监听 `http://127.0.0.1:6131`。
+
+`6131` 是应用提供给本机集成使用的 API 端口，不是 Vite 的页面端口。
+
+## Go 命令找不到
+
+如果 `pnpm dev` 在构建微信连接器时出现 `spawnSync go ENOENT`，先执行：
+
+```bash
+go version
+```
+
+命令不可用表示当前终端的 `PATH` 没有找到 Go。Windows 默认安装位置是 `C:\Program Files\Go\bin`。确认 Go 已安装并把该目录加入系统 `PATH` 后，关闭并重新打开终端或 IDE，再重新执行 `go version` 和 `pnpm dev`。
+
+如果 Go 刚完成安装，已经打开的终端不会自动继承新的环境变量；重开终端是必要步骤。不要绕过连接器构建直接启动 `electron-vite dev`，否则 Agent Hub 的微信连接器不会生成。
+
+## Electron 二进制缺失或下载失败
+
+`electron-vite dev` 报 `Electron uninstall`，或 Electron 安装器报 `fetch failed`，通常表示 `node_modules/electron/dist` 中的 Electron 二进制缺失或下载未完成。这不是应用业务代码的启动错误。
+
+项目的 [`.npmrc`](../../.npmrc) 已设置：
+
+```ini
+electron_mirror=https://npmmirror.com/mirrors/electron/
+```
+
+pnpm 会把该值传给 Electron 安装器，令其从镜像下载与 `package.json` 锁定版本匹配的二进制文件，避免默认 GitHub 下载源在受限网络中不可访问。
+
+依赖安装被中断或 Electron 目录不完整时，删除不完整的 `node_modules` 后重新安装：
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+单次安装需要使用其他镜像时，可以临时覆盖项目默认值。PowerShell 示例：
+
+```powershell
+$env:ELECTRON_MIRROR = 'https://your-electron-mirror.example/'
+pnpm install --frozen-lockfile
+```
+
+该环境变量只影响当前终端，不会改写仓库中的 `.npmrc`。镜像地址必须保留末尾的 `/`，并提供与 Electron 版本对应的目录结构。
+
+## 页面地址无法通过 IPv4 访问
+
+Vite 在某些 Windows 环境中只监听 IPv6 本机回环地址 `::1`。这时直接访问 `http://127.0.0.1:5173/` 可能失败，但 `http://localhost:5173/` 仍然正常，Electron 也会使用后者加载页面。
+
+排查时优先访问 `http://localhost:5173/`；需要显式验证 IPv6 时，使用 `http://[::1]:5173/`。不要因为 IPv4 回环地址不可用就判断 Electron 或 Vite 启动失败。
+
+## 仍无法启动时
+
+保留首次错误的完整输出，并同时记录操作系统、Node.js、pnpm 和 Go 版本，以及 `pnpm install --frozen-lockfile` 与 `pnpm dev` 的执行结果。不要提交数据库密钥、AI API Key、微信数据路径或聊天内容。
diff --git a/docs/development/overview.md b/docs/development/overview.md
index 343595c..a42e2bf 100644
--- a/docs/development/overview.md
+++ b/docs/development/overview.md
@@ -18,6 +18,8 @@ pnpm install
 pnpm dev
 ```
 
+本地依赖安装、Go 环境和 Electron 二进制下载异常，请查看[本地启动排障](./local-startup-troubleshooting.md)。
+
 常用检查：
 
 ```bash