create-arsh-electron：2026 Electron 脚手架

2026 年给 Electron 桌面应用选脚手架，可以多看一眼我们自己的方案：create-arsh-electron 已发布 npm，一条 npm create arsh-electron@latest 出项目——Electron 42 + Vite 8 + React 19 + TypeScript 6 + Tailwind CSS 4，外加无边框窗口、一套桌面 UI 组件、vitest 测试基线和 GitHub Actions CI。姊妹篇里 create-electron-vite 的四个 build 坑（TS6133、二进制下载失败、asar 虚胖、幽灵文件），在它这里全部是出厂默认状态。实测从敲命令到打出 Windows 安装包：0.5 秒生成 + 35.2 秒构建，asar 0.26 MB。

这篇是 Electron 系列的第三篇，也是收官：第一篇讲怎么用官方脚手架建项目、接 AI 编程；第二篇讲四个 build 坑怎么修；这一篇讲我们怎么把修复直接固化成脚手架，以及用它起一个真实项目的完整实测。

要点前置：

• npm create arsh-electron@latest <项目名>，问答只有两个（项目名、是否 git init），name / productName / appId / author 全部自动派生
• 前两篇的四个 build 坑出厂修平：asar 从官方模板的 4.9 MB 降到 0.26 MB
• 出厂自带无边框窗口 + 8 个 UI 组件 + vitest 测试基线 + GitHub Actions CI + AGENTS.md bootstrap
• Electron 42 行为变化：二进制不再在 npm install 时下载，首次运行才自愈补下

create-arsh-electron 上手：一条命令、两个问答

npm create arsh-electron@latest <项目名>

要求 Node ≥ 20.11。交互只有两问：项目名（已作为参数给出时直接跳过），以及是否顺手 git init 并完成首次提交。其余全部自动派生：package.json 的 name 与 author（取自你的 git config），安装包的 productName（arsh-demo → ArshDemo），appId（默认 com.arshdelight.arshdemo，加 --scope mycompany 可换成 com.mycompany.arshdemo），以及窗口标题和标题栏品牌字。前作里要手动改的 YourAppID / YourAppName 占位符，在这里根本不存在。

图：npm create arsh-electron 的完整交互过程，共两个问题，结尾直接给出下一步命令

生成的关键结构：

├── electron/            # 主进程 + preload
├── src/                 # 渲染进程（React + Tailwind 4）
│   ├── ui/              # 8 个 UI 原语（Button/Dialog/TitleBar…）
│   └── lib/utils.test.ts    # vitest 测试基线
├── .github/workflows/ci.yml  # push/PR 自动跑 lint + tsc + test
├── AGENTS.md            # AI 会话的 bootstrap（见下文）
├── electron-builder.json5   # 打包配置（appId、NSIS、镜像）
└── vite.config.ts

下一步只有三条：cd 进去、npm install、npm run dev。也支持 --yes 跳过全部问答（git init 包含在内），方便脚本调用。实测脚手架本体——拷模板、重命名、git init、首次提交——耗时 0.5 秒。

Electron + Vite + React 的四个 build 坑，出厂全部修平

第二篇给 create-electron-vite 列过统一修复清单，要手工做六件事。同样的坑，create-arsh-electron 的出厂状态：

其中 asar 一条值得展开。模板的 dependencies 恒为空对象，渲染层依赖全在 devDependencies——Vite 反正会把它们编译进 dist/，打进 asar 的只剩你自己的代码。第二篇的判断口诀（「删掉这个包还能跑，就放 devDependencies」）也写进了 AGENTS.md，防止后续 npm install xxx 时顺手装回 dependencies，把 node_modules 又拖进包里。

测试基线同理是「防回退」设计：模板自带一个 cn() 工具函数的 vitest 测试（3 条断言覆盖条件类合并与 tailwind-merge 冲突裁决），CI 在每次 push/PR 跑 lint + tsc + test——测试写的不是模板自己的正确性，而是给你立下第一个可扩展的样板，后面加业务代码照着这个密度写就行。

出厂自带一套桌面 UI

npm run dev 起来的是一个无边框窗口（frame: false），标题栏自绘：左侧品牌字随项目名派生，右侧最小化/最大化/关闭，双击标题栏等效最大化/还原，另有一个可选的置顶（pin）按钮；拖拽区域已处理，纯 Web 环境下还会自动退化为普通标题栏。对内部工具和交付项目来说，这一层通常都要重写一遍，现在出厂即有。

图：生成的项目首次启动画面——无边框窗口、自绘标题栏，起始页只有一个 count 按钮演示热更新

组件层配了 8 个常用原语：AppLayout、TitleBar、NavItem、Button、Dialog、Tooltip、Spinner、Switch，主题走 CSS 变量 + Tailwind CSS 4。想换皮改变量就行；整套不喜欢也可以删掉 src/ui/，不影响打包。

开工第一课写在 AGENTS.md 里

第一篇的结尾我们建议：建完项目第一件事是让 AI 把版本管理基线建好。这个动作现在也出厂化了——脚手架自动完成 git init 和首次提交，之后 AI 的每一轮改动从一开始就可 diff、可回退。

AGENTS.md 的设计有点反直觉：它出厂时尽量不带观点。commit 风格、协作方式、完成标准，这些是每个团队自己的事，脚手架替人决定反而越权。所以它是一个 bootstrap：第一次 AI 会话会做一轮访谈（5 个问题、一轮问完、答 "default" 的直接跳过），把答案改写进这个文件，之后不再问。只有三条硬规则原样保留，因为它们由模板结构决定，不该被访谈推翻：

1. 依赖分区：dependencies 只放主进程运行时包，与 vite.config.ts 的 external 清单同步；
2. 渲染层不碰 Node/Electron API：IPC 一律走 window.ipcRenderer，新通道按 handler → preload → 类型声明三层登记；
3. 完成标准：npm run lint（零警告）+ npx tsc --noEmit + npm test 全过，工作才算交付。

Electron 42 的新变化：二进制首次运行才下载

npm install 7.5 秒就结束了（缓存热），但 node_modules/electron/dist 并不存在；首次 npm run dev 时才打印 Downloading Electron binary...，现场补下运行时。

查了 electron 42 的包结构：它不再带 install 脚本，npm install 阶段完全不下载二进制；改为 index.js 在被 require 时自愈——发现 dist 缺失，就现场执行一遍下载逻辑。相比第二篇描述的 electron 30 时代（install 时下载），下载时机整体后移到了首次运行。

对镜像配置的影响分两半说：

• 渲染侧的 @electron/get 只从环境变量读镜像（npm_config_electron_mirror / ELECTRON_MIRROR）。npm 11 目前仍会把项目 .npmrc 里的 electron_mirror 传给脚本环境（实测有效），但每条 npm 命令都会警告 "Unknown project config"，且下个大版本将停止传递；
• 打包侧的 electron-builder 不受影响——它读自己 json5 配置里的 electronDownload.mirror，不走环境变量。

如果你的 CI 依赖「install 完即可离线构建」，electron 42 起需要在安装后显式补一步下载（跑一次 electron 让它自愈，或直接执行它的 install.js）。

实测数据与版本备查

环境：Windows 11、Node v24.15.0、npm 11.12.1、create-arsh-electron 0.2.0。项目 arsh-demo，零代码改动直接构建：

版本组合：Electron 42.11.8、Vite 8.3.1、React 19.3、TypeScript 6.0、Tailwind CSS 4.3、vitest 4.1、electron-builder 26.15.3；脚手架包本体 78.2 kB、38 个文件。

两个已知小事：默认图标未设置（build 会提示 default Electron icon is used，把 ≥256×256 的 build/icon.png 放进项目即消）；npm 11 的 unknown config 警告（见上一节，等镜像传递方案迁移后随版本处理）。

小结

三部曲到此闭环：踩坑（一）→ 修复（二）→ 固化成脚手架（三）。2026 年要起一个 Electron 桌面应用，不管你是在挑脚手架还是项目模板，都可以先用它起个头：MIT 开源，npm create arsh-electron@latest 即可用。

如果你正打算做一个 Electron 桌面应用，或者正被构建/打包问题卡住——欢迎聊聊。