docs: reorganize docs into guide/ and electron/, add 6 new guide docs, update README
This commit is contained in:
284
docs/electron/mirror-setup.md
Normal file
284
docs/electron/mirror-setup.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# 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 应用了！🎉
|
||||
Reference in New Issue
Block a user