tianshu-engine/docs/electron-mirror-setup.md

# Electron 镜像源配置指南

## 问题描述

打包 Electron 应用时，如果未开启翻墙，会出现 "fetch failed" 错误，这是因为 Electron 和相关工具需要从国外的 GitHub releases 下载二进制文件。

## 解决方案

### 方案 1：使用 npm 配置（推荐）

#### 1.1 全局配置

在项目根目录创建 `.npmrc` 文件：

```ini
registry=https://registry.npmmirror.com
electron_mirror=https://npmmirror.com/mirrors/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/
```

#### 1.2 Electron 目录配置

在 `electron/` 目录创建 `.npmrc` 文件：

```ini
electron_mirror=https://npmmirror.com/mirrors/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/
registry=https://registry.npmmirror.com
```

### 方案 2：使用环境变量（已配置）

#### 2.1 Windows

在 `electron/package.json` 中已经配置：

```json
{
  "scripts": {
    "pack:win": "cross-env ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ node ../scripts/prepare-electron.cjs && npx @electron/packager . MyGame --platform=win32 --arch=x64 --out=../release --overwrite"
  }
}
```

#### 2.2 Mac/Linux

```bash
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/
```

### 方案 3：使用批处理脚本

#### Windows

使用 `scripts/pack-win.bat`：

```batch
@echo off
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
set ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/
call npm run pack:win
```

#### Mac/Linux

使用 `scripts/pack-mac.sh`：

```bash
#!/bin/bash
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/
npm run pack:mac
```

### 方案 4：使用系统环境变量

#### Windows

```powershell
# 临时设置（当前会话）
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
set ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

# 永久设置
setx ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/
setx ELECTRON_BUILDER_BINARIES_MIRROR https://npmmirror.com/mirrors/electron-builder-binaries/
```

#### Mac/Linux

```bash
# 临时设置（当前会话）
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/' >> ~/.bashrc
echo 'export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/' >> ~/.bashrc
source ~/.bashrc
```

## 验证配置

### 检查 npm 配置

```bash
npm config get electron_mirror
npm config get electron_builder_binaries_mirror
```

应该输出：

```
https://npmmirror.com/mirrors/electron/
https://npmmirror.com/mirrors/electron-builder-binaries/
```

### 检查环境变量

#### Windows

```cmd
echo %ELECTRON_MIRROR%
echo %ELECTRON_BUILDER_BINARIES_MIRROR%
```

#### Mac/Linux

```bash
echo $ELECTRON_MIRROR
echo $ELECTRON_BUILDER_BINARIES_MIRROR
```

## 可用的镜像源

### 淘宝镜像（推荐）

```ini
electron_mirror=https://npmmirror.com/mirrors/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/
```

### 华为云镜像

```ini
electron_mirror=https://mirrors.huaweicloud.com/electron/
electron_builder_binaries_mirror=https://mirrors.huaweicloud.com/electron-builder-binaries/
```

### 腾讯云镜像

```ini
electron_mirror=https://mirrors.cloud.tencent.com/npm/electron/
```

## 常见问题

### Q1: 配置后仍然失败

**A:** 检查以下几点：

1. 确认配置已生效
2. 清除 npm 缓存：`npm cache clean --force`
3. 删除 node_modules 重新安装：`rm -rf node_modules && npm install`
4. 检查网络连接

### Q2: 某些包仍然需要翻墙

**A:** 可能是其他依赖包的问题，可以：

1. 检查具体的错误信息
2. 使用 `.npmrc` 配置其他镜像源
3. 手动下载相关包

### Q3: 下载速度慢

**A:** 可以尝试：

1. 更换其他镜像源
2. 使用 CDN 加速
3. 使用代理

### Q4: 如何恢复默认配置

**A:** 删除或注释掉 `.npmrc` 中的相关配置：

```bash
npm config delete electron_mirror
npm config delete electron_builder_binaries_mirror
```

## 完整的打包流程

### 1. 首次配置

```bash
# 安装依赖
npm install
cd electron
npm install

# 配置镜像源（已在 .npmrc 中配置）
# 无需额外操作
```

### 2. 日常打包

```bash
# Windows
npm run pack:win

# Mac
npm run pack:mac
```

### 3. 故障排查

如果打包失败：

```bash
# 1. 检查配置
npm config get electron_mirror

# 2. 清除缓存
npm cache clean --force

# 3. 重新安装依赖
cd electron
rm -rf node_modules
npm install

# 4. 重新打包
npm run pack:win
```

## 其他工具的镜像配置

### yarn

```bash
yarn config set electron_mirror https://npmmirror.com/mirrors/electron/
yarn config set electron_builder_binaries_mirror https://npmmirror.com/mirrors/electron-builder-binaries/
```

### pnpm

```bash
pnpm config set electron_mirror https://npmmirror.com/mirrors/electron/
pnpm config set electron_builder_binaries_mirror https://npmmirror.com/mirrors/electron-builder-binaries/
```

## 性能优化

### 1. 使用缓存

Electron 下载的二进制文件会被缓存，后续打包会更快：

```bash
# 查看缓存位置
npm config get cache

# Windows: C:\Users\<username>\AppData\Roaming\npm-cache
# Mac: ~/.npm
# Linux: ~/.npm
```

### 2. 离线模式

如果已经下载过 Electron，可以设置离线模式：

```bash
export ELECTRON_BUILDER_CACHE=~/.electron
```

## 总结

通过配置镜像源，你可以在不翻墙的情况下成功打包 Electron 应用。推荐使用：

1. **`.npmrc` 配置** - 最简单，一次配置永久生效
2. **环境变量** - 灵活，可以针对不同项目配置
3. **批处理脚本** - 方便，可以一键打包

现在你可以愉快地打包 Electron 应用了！🎉