Electron 开发环境搭建 - 从零开始配置完整开发环境

前言

上一篇文章我们了解了 Electron 的核心优势和适用场景，现在是时候动手搭建开发环境了。

相比传统的桌面开发（Qt、WPF 等），Electron 的环境搭建要简单得多。如果你已经有 Web 开发经验，大部分工具你可能都已经安装好了。但为了确保顺利开发，让我们系统地过一遍完整的配置流程。

这篇文章会详细介绍 Windows、macOS 和 Linux 三个平台的环境搭建，以及常见问题的解决方案。

环境要求概览

最低要求

Node.js: v16.0.0 或更高（推荐 LTS 版本）
npm: v8.0.0 或更高
操作系统:
  - Windows 10+
  - macOS 10.13+
  - Linux (64-bit)

磁盘空间: 至少 2GB 可用空间

推荐配置

Node.js: v18 LTS 或 v20 LTS
包管理器: npm, yarn 或 pnpm
代码编辑器: VS Code
Git: 最新版本

Windows 平台环境搭建

步骤 1：安装 Node.js

方式一：官方安装包（推荐）

# 1. 访问 Node.js 官网
https://nodejs.org/

# 2. 下载 LTS 版本
Node.js 18.x LTS (推荐) 或 Node.js 20.x LTS

# 3. 运行安装程序
- 选择 "Automatically install necessary tools"
- 这会安装 Python 和 C++ 编译工具

方式二：使用 Chocolatey

# 安装 Chocolatey (如果没有)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# 安装 Node.js
choco install nodejs-lts

# 验证安装
node --version
npm --version

方式三：使用 nvm-windows

# 1. 下载 nvm-windows
https://github.com/coreybutler/nvm-windows/releases

# 2. 安装 nvm
# 运行 nvm-setup.exe

# 3. 安装 Node.js
nvm install lts
nvm use lts

# 4. 验证
node --version

步骤 2：安装 Python 和构建工具

Electron 的某些依赖需要编译，需要 Python 和 C++ 编译工具。

# 方式 1：通过 Node.js 安装器安装（推荐）
# 在 Node.js 安装时勾选 "Tools for Native Modules"

# 方式 2：手动安装
# 安装 Python 3
choco install python

# 安装 Visual Studio Build Tools
choco install visualstudio2019buildtools
choco install visualstudio2019-workload-vctools

# 方式 3：使用 windows-build-tools (已废弃，但可能有用)
npm install --global windows-build-tools

步骤 3：安装 Git

# 使用 Chocolatey
choco install git

# 或从官网下载
https://git-scm.com/download/win

# 配置 Git
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

步骤 4：安装 VS Code

# 使用 Chocolatey
choco install vscode

# 或从官网下载
https://code.visualstudio.com/

Windows 常见问题

问题 1：node-gyp 编译错误

错误信息：
gyp ERR! stack Error: Can't find Python executable

解决方案：
# 安装 Python 3
choco install python

# 配置 npm 使用 Python
npm config set python "C:\Python39\python.exe"

问题 2：权限问题

错误信息：
EACCES: permission denied

解决方案：
# 以管理员身份运行 PowerShell
# 或修改 npm 全局目录
npm config set prefix "%APPDATA%\npm"

问题 3：网络问题

# 使用国内镜像
npm config set registry https://registry.npmmirror.com
npm config set electron_mirror https://npmmirror.com/mirrors/electron/

---

macOS 平台环境搭建

步骤 1：安装 Homebrew

# 安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 验证安装
brew --version

步骤 2：安装 Node.js

方式一：使用 Homebrew（推荐）

# 安装 Node.js LTS
brew install node@18

# 或安装最新版本
brew install node

# 验证安装
node --version
npm --version

方式二：使用 nvm

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 加载 nvm
source ~/.zshrc  # 如果使用 zsh
# 或
source ~/.bashrc  # 如果使用 bash

# 安装 Node.js
nvm install --lts
nvm use --lts

# 验证
node --version
npm --version

步骤 3：安装 Xcode Command Line Tools

# Electron 某些依赖需要编译
xcode-select --install

# 验证安装
xcode-select -p
# 应该输出: /Library/Developer/CommandLineTools

步骤 4：安装 Git

# Git 通常随 Xcode Command Line Tools 安装
# 如果没有，使用 Homebrew 安装
brew install git

# 配置 Git
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

步骤 5：安装 VS Code

# 使用 Homebrew Cask
brew install --cask visual-studio-code

# 或从官网下载
https://code.visualstudio.com/

macOS 常见问题

问题 1：权限问题

错误信息：
EACCES: permission denied

解决方案：
# 不要使用 sudo npm install
# 使用 nvm 或修改 npm 目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

问题 2：M1/M2 芯片兼容性

# 检查架构
arch

# 如果需要，使用 Rosetta
arch -x86_64 zsh
npm install

问题 3：证书问题

# 开发阶段可以跳过签名
export CSC_IDENTITY_AUTO_DISCOVERY=false

# 或设置为 false
npm config set electron.builder.skip-signing true

---

Linux 平台环境搭建

Ubuntu/Debian 环境搭建

步骤 1：更新系统

sudo apt update
sudo apt upgrade

步骤 2：安装 Node.js

# 方式 1：使用 NodeSource（推荐）
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# 验证安装
node --version
npm --version

# 方式 2：使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts

步骤 3：安装构建工具

# 安装必需的构建工具
sudo apt install -y \
    build-essential \
    clang \
    libdbus-1-dev \
    libgtk-3-dev \
    libnotify-dev \
    libasound2-dev \
    libcap-dev \
    libcups2-dev \
    libxtst-dev \
    libxss1 \
    libnss3-dev \
    gcc-multilib \
    g++-multilib \
    curl \
    gperf \
    bison \
    python3-dbusmock \
    openjdk-8-jre

步骤 4：安装 Git

sudo apt install -y git

# 配置 Git
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

步骤 5：安装 VS Code

# 使用 snap
sudo snap install --classic code

# 或下载 deb 包
wget https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64 -O vscode.deb
sudo dpkg -i vscode.deb
sudo apt install -f

Fedora/CentOS/RHEL 环境搭建

# 安装 Node.js
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo dnf install -y nodejs

# 安装构建工具
sudo dnf groupinstall "Development Tools"
sudo dnf install -y \
    gtk3-devel \
    libnotify-devel \
    alsa-lib-devel \
    libcap-devel \
    cups-devel \
    libXtst-devel \
    nss-devel

# 安装 Git
sudo dnf install -y git

Arch Linux 环境搭建

# 安装 Node.js
sudo pacman -S nodejs npm

# 安装构建工具
sudo pacman -S base-devel gtk3 libnotify alsa-lib libcap cups libxtst nss

# 安装 Git
sudo pacman -S git

Linux 常见问题

问题 1：缺少依赖

错误信息：
error while loading shared libraries: libXXX.so

解决方案：
# Ubuntu/Debian
sudo apt install -y libgtk-3-dev libnotify-dev libnss3-dev

# Fedora
sudo dnf install -y gtk3-devel libnotify-devel nss-devel

问题 2：沙盒问题

错误信息：
FATAL:setuid_sandbox_host.cc(158)] The SUID sandbox helper binary was found

解决方案：
# 开发时禁用沙盒（不推荐生产环境）
electron --no-sandbox

# 或设置环境变量
export ELECTRON_DISABLE_SANDBOX=1

问题 3：权限问题

# 不要使用 sudo 安装全局包
# 使用 nvm 或配置 npm 目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

---

安装和配置 Electron CLI

全局安装 Electron

# 不推荐全局安装，但可以用于快速测试
npm install -g electron

# 验证安装
electron --version

项目级安装（推荐）

# 创建项目目录
mkdir my-electron-app
cd my-electron-app

# 初始化 npm 项目
npm init -y

# 安装 Electron
npm install --save-dev electron

# 验证
npx electron --version

VS Code 配置优化

推荐的扩展

{
  "recommendations": [
    "dbaeumer.vscode-eslint",           // ESLint
    "esbenp.prettier-vscode",           // Prettier
    "ms-vscode.vscode-typescript-next", // TypeScript
    "christian-kohler.npm-intellisense",// npm 智能提示
    "eg2.vscode-npm-script",            // npm 脚本
    "formulahendry.auto-rename-tag",    // 自动重命名标签
    "xabikos.javascriptsnippets"        // JS 代码片段
  ]
}

VS Code 设置

创建 .vscode/settings.json：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "javascript.updateImportsOnFileMove.enabled": "always",
  "typescript.updateImportsOnFileMove.enabled": "always",
  "files.associations": {
    "*.js": "javascript"
  },
  "emmet.includeLanguages": {
    "javascript": "javascriptreact"
  }
}

调试配置

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Electron: Main",
      "type": "node",
      "request": "launch",
      "protocol": "inspector",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "runtimeArgs": ["--remote-debugging-port=9223", "."],
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      }
    },
    {
      "name": "Electron: Renderer",
      "type": "chrome",
      "request": "attach",
      "port": 9223,
      "webRoot": "${workspaceFolder}",
      "timeout": 30000
    }
  ],
  "compounds": [
    {
      "name": "Electron: All",
      "configurations": ["Electron: Main", "Electron: Renderer"]
    }
  ]
}

配置开发工具

安装 Electron Devtools

npm install --save-dev electron-devtools-installer

// main.js
const { app, BrowserWindow } = require('electron')
const { default: installExtension, REACT_DEVELOPER_TOOLS } = require('electron-devtools-installer')

app.whenReady().then(() => {
  if (process.env.NODE_ENV === 'development') {
    installExtension(REACT_DEVELOPER_TOOLS)
      .then((name) => console.log(`Added Extension:  ${name}`))
      .catch((err) => console.log('An error occurred: ', err))
  }
})

配置热重载

npm install --save-dev electron-reload

// main.js
if (process.env.NODE_ENV === 'development') {
  require('electron-reload')(__dirname, {
    electron: require(`${__dirname}/node_modules/electron`)
  })
}

配置 nodemon（推荐）

npm install --save-dev nodemon

// package.json
{
  "scripts": {
    "dev": "nodemon --exec electron ."
  }
}

// nodemon.json
{
  "watch": ["main.js", "preload.js"],
  "ext": "js,json",
  "ignore": ["node_modules/", "dist/"]
}

环境验证

创建一个简单的测试项目来验证环境：

1. 创建项目结构

mkdir electron-env-test
cd electron-env-test
npm init -y
npm install --save-dev electron

2. 创建主进程文件

// main.js
const { app, BrowserWindow } = require('electron')
const path = require('path')

function createWindow() {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false
    }
  })

  win.loadFile('index.html')
  
  // 开发模式打开开发者工具
  if (process.env.NODE_ENV === 'development') {
    win.webContents.openDevTools()
  }
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow()
    }
  })
})

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }
})

3. 创建预加载脚本

// preload.js
const { contextBridge } = require('electron')

contextBridge.exposeInMainWorld('electron', {
  version: process.versions.electron,
  node: process.versions.node,
  chrome: process.versions.chrome
})

4. 创建渲染进程页面

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Electron Environment Test</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
      display: flex;
      justify-content: center;
      align-items: center;
      height: 100vh;
      margin: 0;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
    }
    .container {
      text-align: center;
      padding: 40px;
      background: rgba(255, 255, 255, 0.1);
      border-radius: 20px;
      backdrop-filter: blur(10px);
    }
    h1 { margin: 0 0 20px 0; }
    .info { margin: 10px 0; font-size: 18px; }
  </style>
</head>
<body>
  <div class="container">
    <h1>🎉 Electron Environment Test</h1>
    <div class="info">Electron: <span id="electron-version"></span></div>
    <div class="info">Node.js: <span id="node-version"></span></div>
    <div class="info">Chromium: <span id="chrome-version"></span></div>
    <p style="margin-top: 30px;">✅ Your Electron development environment is ready!</p>
  </div>

  <script>
    document.getElementById('electron-version').textContent = window.electron.version
    document.getElementById('node-version').textContent = window.electron.node
    document.getElementById('chrome-version').textContent = window.electron.chrome
  </script>
</body>
</html>

5. 配置 package.json

{
  "name": "electron-env-test",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "dev": "cross-env NODE_ENV=development electron ."
  },
  "devDependencies": {
    "electron": "^28.0.0",
    "cross-env": "^7.0.3"
  }
}

6. 运行测试

# 安装 cross-env
npm install --save-dev cross-env

# 运行应用
npm run dev

如果看到窗口显示版本信息，说明环境配置成功！

性能优化建议

1. 使用 pnpm 或 yarn

# pnpm（推荐，节省磁盘空间）
npm install -g pnpm
pnpm install electron

# yarn
npm install -g yarn
yarn add electron --dev

2. 配置镜像

# npm 镜像
npm config set registry https://registry.npmmirror.com
npm config set electron_mirror https://npmmirror.com/mirrors/electron/

# pnpm 镜像
pnpm config set registry https://registry.npmmirror.com
pnpm config set electron_mirror https://npmmirror.com/mirrors/electron/

3. 使用缓存

# 清理缓存（如果遇到问题）
npm cache clean --force

# 使用离线模式（如果已有缓存）
npm install --prefer-offline

总结

环境搭建完成！让我们回顾一下关键步骤：

✅ 核心组件

组件	Windows	macOS	Linux
Node.js	✓	✓	✓
npm	✓	✓	✓
Python	✓	系统自带	✓
编译工具	MSVC	Xcode CLT	GCC
Git	✓	✓	✓
VS Code	✓	✓	✓

🎯 检查清单

# ✅ 确认以下命令都能正常运行
node --version
npm --version
git --version
electron --version  # 如果全局安装了

💡 新手提示

1. 推荐使用 nvm

   • 可以轻松切换 Node.js 版本
   • 避免权限问题

2. 使用国内镜像

   • 大幅提升安装速度
   • 减少网络问题

3. 配置好 IDE

   • VS Code 扩展很重要
   • 调试配置能节省大量时间

🚀 下一步

环境搭建完成后，你已经准备好开始 Electron 开发了！

下一篇文章，我们将：

• 创建第一个 Electron 应用
• 了解项目结构
• 实现基本功能
• 调试和测试

---

相关文章推荐：

• 上一篇：Electron 是什么？桌面应用开发的王者框架
• 下一篇：Electron 快速开始 - 30 分钟创建第一个应用

遇到问题？欢迎在评论区留言，我会及时解答！

---

参考资料：

• Electron 官方文档
• Node.js 官网
• nvm GitHub