{"id":18976791,"url":"https://github.com/yanyue404/electron-quick-start","last_synced_at":"2026-04-26T16:32:32.751Z","repository":{"id":110129212,"uuid":"218814320","full_name":"yanyue404/electron-quick-start","owner":"yanyue404","description":null,"archived":false,"fork":false,"pushed_at":"2020-07-07T09:11:02.000Z","size":7,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-02T14:52:28.155Z","etag":null,"topics":["electron"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yanyue404.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-31T16:47:53.000Z","updated_at":"2019-11-06T04:33:34.000Z","dependencies_parsed_at":"2023-03-27T23:15:15.643Z","dependency_job_id":null,"html_url":"https://github.com/yanyue404/electron-quick-start","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yanyue404/electron-quick-start","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanyue404%2Felectron-quick-start","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanyue404%2Felectron-quick-start/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanyue404%2Felectron-quick-start/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanyue404%2Felectron-quick-start/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yanyue404","download_url":"https://codeload.github.com/yanyue404/electron-quick-start/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanyue404%2Felectron-quick-start/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32305035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron"],"created_at":"2024-11-08T15:26:20.523Z","updated_at":"2026-04-26T16:32:32.738Z","avatar_url":"https://github.com/yanyue404.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# electron-quick-start\n\n基于 **Electron + Vite + Vue 3** 的多页桌面应用模板，主页使用经典 TodoMVC 案例。\n\n---\n\n## 项目结构\n\n```\nelectron-quick-start/\n├── electron/                    # Electron 主进程代码\n│   ├── main.js                  #   主进程入口（窗口管理、IPC 通信）\n│   └── preload.js               #   预加载脚本（contextBridge 桥接）\n├── src/                         # 渲染进程代码（Vue 3 应用）\n│   ├── pages/\n│   │   ├── main/                #   主页 - TodoMVC\n│   │   │   ├── App.vue          #     根组件\n│   │   │   ├── main.js          #     页面入口\n│   │   │   └── components/      #     页面组件\n│   │   │       ├── TodoHeader.vue\n│   │   │       ├── TodoList.vue\n│   │   │       ├── TodoItem.vue\n│   │   │       └── TodoFooter.vue\n│   │   └── about/               #   关于页\n│   │       ├── App.vue\n│   │       └── main.js\n│   └── styles/                  # 全局样式\n│       ├── base.css\n│       ├── todomvc.css\n│       └── about.css\n├── public/                      # 静态资源（不参与构建）\n│   └── icon.png                 #   应用图标（打包时使用）\n├── index.html                   # 主页 HTML 入口\n├── about.html                   # 关于页 HTML 入口\n├── vite.config.js               # Vite + Electron 插件配置\n├── package.json                 # 项目配置 \u0026 electron-builder 打包配置\n├── .nvmrc                       # Node 版本锁定（18）\n├── .npmrc                       # npm 镜像配置\n└── .editorconfig                # 编辑器格式化配置\n```\n\n### 构建产物目录（gitignore）\n\n```\n├── dist/                        # Vite 构建的前端资源\n├── dist-electron/               # Vite 构建的 Electron 主进程 \u0026 preload\n└── release/                     # electron-builder 打包产物（exe/dmg 等）\n```\n\n---\n\n## 技术栈\n\n| 技术                 | 版本    | 说明                         |\n| -------------------- | ------- | ---------------------------- |\n| **Electron**         | ^28.0.0 | 桌面应用框架（内置 Node 18） |\n| **Vite**             | ^5.4.0  | 前端构建工具                 |\n| **Vue**              | ^3.4.0  | 前端框架（Composition API）  |\n| **electron-builder** | ^24.9.0 | 应用打包工具                 |\n| **Node 环境**        | \u003e=18    | 运行环境（`.nvmrc` 锁定）    |\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\n# 确保使用 Node 18+\nnode -v\n\n# 安装依赖\nnpm install\n```\n\n### 2. 启动开发模式\n\n```bash\nnpm run dev\n```\n\n启动后会自动：\n\n- 启动 Vite 开发服务器（默认 http://localhost:5173）\n- 构建 Electron 主进程和 preload 脚本\n- 打开 Electron 窗口加载主页\n\n\u003e 修改渲染进程代码（Vue 组件、样式）会自动热更新（HMR），无需重启。\n\u003e 修改主进程 / preload 代码会自动重新构建并重载窗口。\n\n---\n\n## 调试开发\n\n### 渲染进程调试（前端页面）\n\n在 Electron 窗口中，使用快捷键打开 DevTools：\n\n| 平台    | 快捷键                      |\n| ------- | --------------------------- |\n| Windows | `Ctrl + Shift + I` 或 `F12` |\n| macOS   | `Cmd + Option + I`          |\n\n也可以在 `electron/main.js` 中取消注释来默认打开 DevTools：\n\n```js\n// 在 createMainWindow 函数中添加：\nmainWindow.webContents.openDevTools();\n```\n\n### 主进程调试\n\n**方式一：VS Code 调试**\n\n创建 `.vscode/launch.json`：\n\n```json\n{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    {\n      \"name\": \"Debug Electron Main\",\n      \"type\": \"node\",\n      \"request\": \"launch\",\n      \"cwd\": \"${workspaceFolder}\",\n      \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n      \"args\": [\".\", \"--remote-debugging-port=9222\"],\n      \"windows\": {\n        \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n      },\n      \"outputCapture\": \"std\",\n      \"sourceMaps\": true\n    }\n  ]\n}\n```\n\n\u003e 注意：使用此方式前需先运行 `npm run build` 构建一次。\n\n**方式二：console.log 日志**\n\n主进程中的 `console.log` 输出会打印在启动终端中，可直接查看。\n\n### 渲染进程 Vue Devtools\n\n安装 Vue Devtools 浏览器扩展后，在 Electron DevTools 中可直接使用。也可以使用独立版：\n\n```bash\n# 安装独立 Vue Devtools\nnpm install -g @vue/devtools\n\n# 启动\nvue-devtools\n```\n\n然后在 `index.html` 的 `\u003chead\u003e` 中添加：\n\n```html\n\u003cscript src=\"http://localhost:8098\"\u003e\u003c/script\u003e\n```\n\n---\n\n## 打包构建\n\n### 构建前端资源（不打包 exe）\n\n```bash\nnpm run build\n```\n\n产物输出到 `dist/` 和 `dist-electron/` 目录。\n\n### 打包为安装程序（exe / dmg / AppImage）\n\n```bash\n# 打包为安装程序\nnpm run build:exe\n\n# 仅生成免安装目录（调试打包问题时使用）\nnpm run build:exe:dir\n```\n\n产物输出到 `release/` 目录。\n\n### 打包配置说明\n\n打包配置位于 `package.json` 的 `\"build\"` 字段：\n\n```jsonc\n{\n  \"build\": {\n    \"appId\": \"com.electron.quick-start\", // 应用唯一标识\n    \"productName\": \"Electron Quick Start\", // 应用显示名称\n    \"directories\": {\n      \"output\": \"release\" // 打包输出目录\n    },\n    \"files\": [\n      // 需要打包的文件\n      \"dist/**/*\",\n      \"dist-electron/**/*\"\n    ],\n    \"win\": {\n      // Windows 平台配置\n      \"target\": [{ \"target\": \"nsis\", \"arch\": [\"x64\"] }],\n      \"icon\": \"public/icon.png\" // 应用图标（至少 256x256）\n    },\n    \"nsis\": {\n      // NSIS 安装程序配置\n      \"oneClick\": false, // 非一键安装\n      \"allowToChangeInstallationDirectory\": true // 允许选择安装目录\n    }\n  }\n}\n```\n\n### 应用图标\n\n- 放置位置：`public/icon.png`\n- Windows：建议 256x256 或更大的 `.png` / `.ico`\n- macOS：建议 512x512 的 `.png` / `.icns`\n\n\u003e 如果没有提供图标文件，electron-builder 会使用默认图标。\n\n---\n\n## 新增页面\n\n以新增一个 **设置页（Settings）** 为例，需要 4 步：\n\n### 步骤 1：创建 HTML 入口\n\n在项目根目录创建 `settings.html`：\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"zh-CN\"\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"UTF-8\" /\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" /\u003e\n    \u003ctitle\u003e设置 - Electron\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv id=\"app\"\u003e\u003c/div\u003e\n    \u003cscript type=\"module\" src=\"/src/pages/settings/main.js\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### 步骤 2：创建 Vue 页面\n\n创建 `src/pages/settings/main.js`：\n\n```js\nimport { createApp } from \"vue\";\nimport App from \"./App.vue\";\n\ncreateApp(App).mount(\"#app\");\n```\n\n创建 `src/pages/settings/App.vue`：\n\n```vue\n\u003ctemplate\u003e\n  \u003cdiv class=\"settings\"\u003e\n    \u003ch1\u003e设置\u003c/h1\u003e\n    \u003c!-- 页面内容 --\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\n// 组件逻辑\n\u003c/script\u003e\n\n\u003cstyle scoped\u003e\n/* 页面样式 */\n\u003c/style\u003e\n```\n\n### 步骤 3：注册到 Vite 多页配置\n\n在 `vite.config.js` 中的 `build.rollupOptions.input` 添加新入口：\n\n```js\nbuild: {\n  rollupOptions: {\n    input: {\n      main: resolve(__dirname, \"index.html\"),\n      about: resolve(__dirname, \"about.html\"),\n      settings: resolve(__dirname, \"settings.html\"),  // ← 新增\n    },\n  },\n},\n```\n\n### 步骤 4：在主进程中创建窗口\n\n在 `electron/main.js` 中添加窗口创建函数：\n\n```js\nlet settingsWindow;\n\nfunction createSettingsWindow() {\n  if (settingsWindow) {\n    settingsWindow.focus();\n    return;\n  }\n\n  settingsWindow = new BrowserWindow({\n    width: 600,\n    height: 400,\n    parent: mainWindow,\n    webPreferences: {\n      preload: path.join(__dirname, \"preload.js\"),\n      contextIsolation: true,\n      nodeIntegration: false,\n    },\n  });\n\n  if (process.env.VITE_DEV_SERVER_URL) {\n    settingsWindow.loadURL(`${process.env.VITE_DEV_SERVER_URL}settings.html`);\n  } else {\n    settingsWindow.loadFile(path.join(process.env.DIST, \"settings.html\"));\n  }\n\n  settingsWindow.on(\"closed\", () =\u003e {\n    settingsWindow = null;\n  });\n}\n\n// 注册 IPC 监听\nipcMain.on(\"open-settings\", () =\u003e {\n  createSettingsWindow();\n});\n```\n\n如需从渲染进程打开该窗口，在 `electron/preload.js` 中暴露 API：\n\n```js\ncontextBridge.exposeInMainWorld(\"electronAPI\", {\n  // ...已有 API\n  openSettings: () =\u003e ipcRenderer.send(\"open-settings\"),\n});\n```\n\n---\n\n## 核心概念\n\n### 进程架构\n\n```\n┌─────────────────────────────────────────────────┐\n│                  Electron 应用                   │\n│                                                  │\n│  ┌──────────────┐                                │\n│  │  主进程       │  electron/main.js              │\n│  │  (Node.js)   │  - 窗口管理                     │\n│  │              │  - IPC 通信                      │\n│  │              │  - 系统 API 调用                  │\n│  └──────┬───────┘                                │\n│         │ contextBridge (preload.js)              │\n│  ┌──────┴───────┐  ┌──────────────┐              │\n│  │  渲染进程 1   │  │  渲染进程 2   │              │\n│  │  (主页)      │  │  (关于页)     │   ...更多窗口 │\n│  │  index.html  │  │  about.html  │              │\n│  │  Vue 3 App   │  │  Vue 3 App   │              │\n│  └──────────────┘  └──────────────┘              │\n└─────────────────────────────────────────────────┘\n```\n\n### IPC 通信模式\n\n渲染进程与主进程之间通过 `preload.js` 的 `contextBridge` 安全通信：\n\n```\n渲染进程                    preload.js                主进程\n(Vue 组件)               (contextBridge)          (electron/main.js)\n    │                         │                        │\n    │  window.electronAPI     │                        │\n    │  .openAbout()           │                        │\n    ├────────────────────────►│  ipcRenderer.send()    │\n    │                         ├───────────────────────►│\n    │                         │                        │  createAboutWindow()\n    │                         │                        │\n```\n\n**单向通信（渲染 → 主进程）：**\n\n```js\n// preload.js\nopenAbout: () =\u003e ipcRenderer.send(\"open-about\");\n\n// main.js\nipcMain.on(\"open-about\", () =\u003e {\n  /* 处理 */\n});\n```\n\n**双向通信（请求-响应）：**\n\n```js\n// preload.js\ngetData: () =\u003e ipcRenderer.invoke(\"get-data\");\n\n// main.js\nipcMain.handle(\"get-data\", async () =\u003e {\n  return { key: \"value\" };\n});\n\n// Vue 组件中\nconst data = await window.electronAPI.getData();\n```\n\n---\n\n## 常用命令一览\n\n| 命令                    | 说明                                 |\n| ----------------------- | ------------------------------------ |\n| `npm run dev`           | 启动开发模式（Vite HMR + Electron）  |\n| `npm run build`         | 构建前端资源                         |\n| `npm run build:exe`     | 构建并打包为安装程序（exe / dmg 等） |\n| `npm run build:exe:dir` | 构建并生成免安装目录（用于调试打包） |\n| `npm run preview`       | 预览构建后的前端页面                 |\n\n---\n\n## 常见问题\n\n### Q: 开发时修改代码后 Electron 窗口没有更新？\n\n- 渲染进程（Vue 组件、CSS）修改后会自动 HMR\n- 主进程 / preload 修改后会自动重新构建，但可能需要手动关闭重开窗口\n- 如果仍然不更新，可以用 `Ctrl+R` 刷新窗口\n\n### Q: 打包时报错找不到图标？\n\n确保 `public/icon.png` 文件存在，或者在 `package.json` 的 `build` 配置中删除 `icon` 字段使用默认图标。\n\n### Q: 如何在渲染进程中使用 Node.js API？\n\n出于安全考虑，渲染进程默认禁用了 `nodeIntegration`。请通过 `preload.js` 使用 `contextBridge` 暴露需要的 API，不要直接启用 `nodeIntegration`。\n\n### Q: 打包后应用白屏？\n\n检查 `electron/main.js` 中 `process.env.DIST` 路径是否正确指向 `dist` 目录，确保 `vite build` 已正确执行。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanyue404%2Felectron-quick-start","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyanyue404%2Felectron-quick-start","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanyue404%2Felectron-quick-start/lists"}