环境搭建 #
一、环境要求 #
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