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

Electron 镜像源配置指南

问题描述

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

解决方案

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

1.1 全局配置

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

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 文件：

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 中已经配置：

{
  "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

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：

@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：

#!/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

# 临时设置（当前会话）
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

# 临时设置（当前会话）
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 配置

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

echo %ELECTRON_MIRROR%
echo %ELECTRON_BUILDER_BINARIES_MIRROR%

Mac/Linux

echo $ELECTRON_MIRROR
echo $ELECTRON_BUILDER_BINARIES_MIRROR

可用的镜像源

淘宝镜像（推荐）

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

华为云镜像

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

腾讯云镜像

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 中的相关配置：

npm config delete electron_mirror
npm config delete electron_builder_binaries_mirror

完整的打包流程

1. 首次配置

# 安装依赖
npm install
cd electron
npm install

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

2. 日常打包

# Windows
npm run pack:win

# Mac
npm run pack:mac

3. 故障排查

如果打包失败：

# 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

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

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 下载的二进制文件会被缓存，后续打包会更快：

# 查看缓存位置
npm config get cache

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

2. 离线模式

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

export ELECTRON_BUILDER_CACHE=~/.electron

总结

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

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

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