环境搭建 #

一、环境要求 #

1.1 系统要求 #

系统 最低版本 推荐版本
Windows Windows 10 Windows 10/11
macOS macOS 10.15 macOS 12+
Linux Ubuntu 18.04 Ubuntu 22.04

1.2 软件要求 #

软件 最低版本 推荐版本
Node.js 16.x 20.x LTS
npm 8.x 10.x
Git 2.x 最新版

二、安装 Node.js #

2.1 Windows 安装 #

方式一:官网下载

text
1. 访问 https://nodejs.org/
2. 下载 LTS 版本安装包
3. 运行安装程序,按提示完成安装

方式二:使用 nvm-windows

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

# 安装 Node.js
nvm install 20
nvm use 20

# 验证安装
node -v
npm -v

2.2 macOS 安装 #

方式一:官网下载

text
1. 访问 https://nodejs.org/
2. 下载 macOS 安装包
3. 运行安装程序

方式二:使用 Homebrew

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

# 安装 Node.js
brew install node

# 验证安装
node -v
npm -v

方式三:使用 nvm

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

# 重新加载终端配置
source ~/.zshrc

# 安装 Node.js
nvm install 20
nvm use 20

# 验证安装
node -v
npm -v

2.3 Linux 安装 #

Ubuntu/Debian

bash
# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v
npm -v

CentOS/RHEL

bash
# 使用 NodeSource 仓库
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node -v
npm -v

三、配置 npm 镜像 #

3.1 切换淘宝镜像 #

bash
# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry

3.2 使用 nrm 管理镜像源 #

bash
# 安装 nrm
npm install -g nrm

# 查看可用镜像源
nrm ls

# 切换镜像源
nrm use taobao

# 测试镜像速度
nrm test

3.3 设置 Electron 镜像 #

bash
# 设置 Electron 下载镜像
npm config set electron_mirror https://npmmirror.com/mirrors/electron/

# 或在项目 .npmrc 文件中添加
echo "electron_mirror=https://npmmirror.com/mirrors/electron/" >> .npmrc

四、创建 Electron 项目 #

4.1 方式一:手动创建 #

步骤1:创建项目目录

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

步骤2:初始化项目

bash
# 初始化 npm 项目
npm init -y

步骤3:安装 Electron

bash
# 安装 Electron 为开发依赖
npm install electron --save-dev

步骤4:修改 package.json

json
{
    "name": "my-electron-app",
    "version": "1.0.0",
    "main": "main.js",
    "scripts": {
        "start": "electron .",
        "dev": "electron . --enable-logging"
    },
    "devDependencies": {
        "electron": "^28.0.0"
    }
}

4.2 方式二:使用脚手架 #

使用 Electron Forge

bash
# 全局安装 Electron Forge
npm install -g @electron-forge/cli

# 创建新项目
npx create-electron-app my-app

# 进入项目目录
cd my-app

# 启动开发服务器
npm start

使用 Electron React Boilerplate

bash
# 克隆模板
git clone --depth 1 --single-branch https://github.com/electron-react-boilerplate/electron-react-boilerplate.git my-app

# 进入项目目录
cd my-app

# 安装依赖
npm install

# 启动开发服务器
npm start

4.3 方式三:使用 Vite + Electron #

bash
# 创建 Vite 项目
npm create vite@latest my-electron-app -- --template react

# 进入项目目录
cd my-electron-app

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

# 安装 Vite Electron 插件
npm install vite-plugin-electron --save-dev

五、开发工具配置 #

5.1 VS Code 配置 #

推荐扩展

扩展名 用途
ESLint 代码检查
Prettier 代码格式化
Electron Electron 代码片段
Path Intellisense 路径自动补全

launch.json 配置

json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Electron: Main Process",
            "type": "node",
            "request": "launch",
            "cwd": "${workspaceFolder}",
            "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
            "args": ["."],
            "outputCapture": "std"
        },
        {
            "name": "Electron: Renderer Process",
            "type": "chrome",
            "request": "attach",
            "port": 9222,
            "webRoot": "${workspaceFolder}"
        }
    ]
}

5.2 ESLint 配置 #

安装 ESLint

bash
npm install eslint --save-dev
npx eslint --init

.eslintrc.js 配置

javascript
module.exports = {
    env: {
        browser: true,
        es2021: true,
        node: true
    },
    extends: 'eslint:recommended',
    parserOptions: {
        ecmaVersion: 'latest',
        sourceType: 'module'
    },
    rules: {
        'no-unused-vars': 'warn',
        'no-console': 'off'
    }
};

5.3 Prettier 配置 #

安装 Prettier

bash
npm install prettier --save-dev

.prettierrc 配置

json
{
    "semi": true,
    "singleQuote": true,
    "tabWidth": 4,
    "trailingComma": "es5",
    "printWidth": 100
}

六、项目结构规范 #

6.1 基础项目结构 #

text
my-electron-app/
├── src/
│   ├── main/           # 主进程代码
│   │   └── index.js
│   ├── renderer/       # 渲染进程代码
│   │   ├── index.html
│   │   ├── index.js
│   │   └── styles.css
│   └── preload/        # 预加载脚本
│       └── index.js
├── assets/             # 静态资源
│   ├── icons/
│   └── images/
├── build/              # 构建配置
├── dist/               # 打包输出
├── .npmrc              # npm 配置
├── package.json
└── README.md

6.2 推荐的项目结构 #

text
my-electron-app/
├── electron/
│   ├── main.js         # 主进程入口
│   ├── preload.js      # 预加载脚本
│   └── utils/          # 主进程工具函数
├── src/                # 渲染进程源码
│   ├── components/     # 组件目录
│   ├── pages/          # 页面目录
│   ├── styles/         # 样式目录
│   ├── utils/          # 工具函数
│   └── index.html      # 入口页面
├── resources/          # 资源文件
│   ├── icons/          # 图标
│   └── images/         # 图片
├── scripts/            # 脚本文件
├── tests/              # 测试文件
├── .eslintrc.js
├── .prettierrc
├── package.json
└── electron-builder.yml

七、开发调试 #

7.1 启动开发模式 #

bash
# 启动 Electron
npm start

# 带日志输出启动
npm run dev

7.2 开发者工具 #

javascript
// 在主进程中打开开发者工具
mainWindow.webContents.openDevTools();

// 快捷键
// Windows/Linux: Ctrl + Shift + I
// macOS: Cmd + Option + I

7.3 热重载配置 #

使用 electron-reload

bash
npm install electron-reload --save-dev
javascript
// main.js
const electron = require('electron');

// 开发模式下启用热重载
if (process.env.NODE_ENV === 'development') {
    require('electron-reload')(__dirname, {
        electron: require(`${__dirname}/node_modules/electron`)
    });
}

使用 nodemon

bash
npm install nodemon --save-dev
json
// package.json
{
    "scripts": {
        "dev": "nodemon --exec electron ."
    }
}

八、常见问题 #

8.1 Electron 下载慢 #

bash
# 设置镜像源
npm config set electron_mirror https://npmmirror.com/mirrors/electron/

# 或使用环境变量
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

8.2 Node 版本问题 #

bash
# 使用 nvm 切换 Node 版本
nvm install 20
nvm use 20

# 查看当前版本
node -v

8.3 权限问题 #

bash
# macOS/Linux 修复 npm 权限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

九、总结 #

9.1 环境检查清单 #

检查项 命令
Node.js 版本 node -v
npm 版本 npm -v
Electron 版本 npm list electron
Git 版本 git --version

9.2 下一步 #

环境搭建完成后,接下来让我们创建 第一个应用,开始你的 Electron 开发之旅!

最后更新:2026-03-28