ecos 是一个非常流行的 Electron 应用程序的 Cross-platOrm Scaffolding tool（跨平台脚手架工具），它极大地简化了使用 Electron API、React、Vue、TypeScript 等现代前端技术来构建桌面应用的初始过程。

什么是 ecos？

ecos 是一个命令行工具，它能帮你快速生成一个结构完整、配置齐全的 Electron 项目，你不再需要从零开始配置 webpack、babel、TypeScript 等一堆复杂的工具，ecos 都帮你做好了。

它的核心特点：

• 跨平台: 生成的项目可以在 Windows, macOS, 和 Linux 上运行。
• 技术栈选择: 可以集成 React, Vue 2, Vue 3, Svelte, 甚至纯 HTML/CSS/JS。
• 现代化: 默认支持 TypeScript, ESLint, Prettier 等现代开发工具。
• 开箱即用: 集成了热重载、自动打包等功能。

安装 ecos

在使用 ecos 之前，你需要先确保你的电脑上已经安装了 Node.js 和 npm (或 yarn/pnpm),你可以通过以下命令检查：

node -v
npm -v

全局安装 ecos 命令行工具：

# 使用 npm
npm install -g @electron-forge/cli
# 或者使用 yarn
yarn global add @electron-forge/cli
# 或者使用 pnpm
pnpm add -g @electron-forge/cli

注意: ecos 实际上是 @electron-forge/cli 的一部分，它是 Electron 官方推荐的脚手架工具，所以安装的是 @electron-forge/cli。

使用 ecos 创建新项目

安装完成后，你就可以用 electron-forge 命令来创建项目了。

第一步：创建项目目录并初始化

# 1. 创建一个新文件夹并进入
mkdir my-electron-app
cd my-electron-app
# 2. 使用 electron-forge 初始化项目
# 这会启动一个交互式命令行界面
npm init electron-forge

第二步：选择项目模板

运行 npm init electron-forge 后,命令行会问你几个问题：

? Would you like to add a TypeScript configuration? (Y/n) y
? Which template would you like to use? (Use arrow keys)
> TypeScript + React
  TypeScript + Vue
  TypeScript + Svelte
  TypeScript + HTML
  JavaScript + React
  JavaScript + Vue
  JavaScript + Svelte
  JavaScript + HTML

• TypeScript/JavaScript: 选择你的语言偏好。
• React/Vue/Svelte/HTML: 选择你的前端框架或纯 HTML。

这里我们以最常用的 TypeScript + React 为例,选中它并按回车。

第三步：等待安装完成

选择模板后，electron-forge 会自动下载并安装所有必需的依赖项，这可能需要几分钟时间，完成后,你的项目目录结构看起来会是这样：

my-electron-app/
├── .gitignore
├── .eslintrc.json
├── .prettierrc
├── forge.config.ts (或 .js)  // Electron Forge 的配置文件
├── out/                     // 打包后的文件会放在这里
├── package.json
├── public/
│   └── favicon.ico
├── src/
│   ├── main/
│   │   └── index.ts         // Electron 主进程代码
│   ├── renderer/
│   │   └── App.tsx          // React 渲染进程代码
│   └── index.html           // 渲染进程的 HTML 模板
├── tsconfig.json            // TypeScript 配置
└── yarn.lock (或 package-lock.json)

核心命令行指令

创建好项目后,你可以在项目根目录下使用以下命令：

npm start 或 electron-forge start

这是你开发时最常用的命令。

• 作用: 启动 Electron 应用。
• 流程:
  1. 启动一个开发服务器来运行你的前端代码（React 应用）。
  2. 启动 Electron 主进程,加载你的前端应用。
  3. 当你修改前端代码时，开发服务器会自动热重载，无需重启整个 Electron 应用。
• 示例:

  npm start

npm run package 或 electron-forge package

当你需要测试一个完整的、可分发的应用包时使用。

• 作用: 将你的应用打包成一个可执行文件（在 macOS 上是 .app，在 Windows 上是 .exe，在 Linux 上是）。
• 流程: 它会编译你的所有代码（TypeScript, SCSS等）,并将所有依赖项和资源文件打包到一个文件夹中。
• 输出位置: 打包后的文件通常位于项目根目录的 out/ 文件夹下。
• 示例:

  npm run package

npm run make 或 electron-forge make

这是生成最终安装包的命令。

• 作用: 在 package 的基础上，进一步将应用打包成针对特定操作系统的安装程序（.dmg, .exe, .deb）。
• 流程: 它会调用系统级的打包工具（如 electron-builder 或 electron-packager）来创建安装程序。
• 输出位置: 生成的安装程序通常位于 out/ 文件夹下的一个子文件夹中（out/my-electron-app-darwin-arm64）。
• 示例:

  npm run make

npm run publish 或 electron-forge publish

• 作用: 将你的应用发布到 GitHub Releases 或其他平台。
• 用途: 通常用于 CI/CD（持续集成/持续部署）流程,实现自动化发布。

项目结构解析

理解 ecos 生成的项目结构对于开发至关重要：

• src/main/index.ts: 主进程。

  • 这是 Electron 应用的心脏，它负责创建和管理浏览器窗口、与原生系统 API 交互（如文件系统、菜单、通知等）。
  • 你在这里加载你的渲染进程（React/Vue 应用）。

• src/renderer/: 渲染进程。

  • 这就是你用 React, Vue 等框架编写的应用程序代码。
  • 它运行在一个类似浏览器的环境中（Chromium）,负责用户界面的展示和交互。

• forge.config.ts: Electron Forge 配置文件。

  这里可以自定义打包、发布等行为的配置，比如应用名称、图标、asar 是否开启等。

• package.json: 项目配置文件。

  • 定义了项目的脚本命令（start, package, make）、依赖项、应用元数据（名称、版本、作者）等。

常见问题与最佳实践

1. 端口冲突: npm start 默认使用 3000 端口，如果该端口被占用，应用会启动失败，你可以在 package.json 的 config.forge.packagerConfig 中修改 electronDist 或其他配置来指定不同端口，或者在启动前确保 3000 端口空闲。

2. 预加载脚本: 为了在渲染进程中安全地使用 Node.js 模块（通过 require），你需要一个预加载脚本，在 forge.config.ts 中，你可以为 mainWindow 的 webPreferences 配置 preload 路径。

3. 调试:

   • 主进程调试: 在 VS Code 中，打开调试面板，选择 "Add Configuration..."，然后选择 "Launch Electron Main Process"，你可以在 src/main/index.ts 中设置断点进行调试。
   • 渲染进程调试: 在应用运行时，右键点击窗口，选择 "检查" 或按 Ctrl+Shift+I (Windows/Linux) 或 Cmd+Option+I (macOS) 打开开发者工具，像调试网页一样调试你的 React/Vue 代码。

4. 从零迁移: 如果你已经有一个 React/Vue 项目，并想把它变成 Electron 应用，你可以手动将 ecos 生成的 src/main 和 src/renderer 目录合并到你现有项目的相应部分，并配置好 package.json 和 forge.config.ts。

ecos (通过 @electron-forge/cli) 是一个强大且高效的工具，能让你专注于业务逻辑，而不是繁琐的配置,希望这份详细的指南能帮助你快速上手！