create-electron-vite 上手：从建项目到 AI 编程

想在 Windows 上快速起一个 Electron 桌面应用，现在最省事的路径是官方脚手架 create-electron-vite：一条命令出项目，TypeScript、热更新、打包配置全部就位。这篇是上手记录：怎么建、模板出厂自带哪些坑、怎么把 AI 编程工具接进来。实测环境 Windows 11 + Node v24.15.0 + create-electron-vite 0.7.1。

四个坑的原理与完整修法在姊妹篇：《create-electron-vite 四个 build 坑与统一修复》，建议两篇一起收藏。

一条命令创建项目：npm create electron-vite

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

按提示回答两件事：

1. Package name：包名（默认 = 目录名，回车即可）
2. Project template：Vue / React / Vanilla（方向键选择，选带 -ts 字样的就是 TypeScript）

生成的关键结构：

├── electron/            # 主进程 + preload（Node 侧代码都在这）
│   ├── main.ts          # 创建窗口、加载页面
│   └── preload.ts       # contextBridge 暴露 ipcRenderer 给渲染层
├── src/                 # 渲染进程（React/Vue 页面代码）
├── vite.config.ts       # electron({ main, preload, renderer }) 三段式插件配置
└── electron-builder.json5   # 打包配置（appId、files、NSIS 等）

三个核心脚本：

npm install     # 装依赖（electron 运行时会一并下载）
npm run dev     # 开发窗口，渲染层热更新
npm run build   # 类型检查 → vite build → electron-builder 出安装包到 release/

两点背景，帮你建立正确预期：

• 实际执行的是 create-electron-vite（命令 cev，当前 0.7.1），纯交互式，暂不支持 --template 之类的非交互参数；
• 它的工作方式是先拷一份 Vite 官方 Web 模板，再把 Electron 层叠加进去（electron/main.ts、electron/preload.ts、electron-builder.json5，并往 build 脚本追加 electron-builder）。所以你得到的是 Vite + vite-plugin-electron + electron-builder 的组合，而不是 electron-vite（alex8088）那个框架。

量级感受（实测）：模板原样 npm run build，React 版 asar 4.9 MB、Vue 版 14.1 MB；按姊妹篇做依赖分区后都回到 0.1 MB——这个体积坑建完项目就值得顺手修掉。

建完项目，先过一遍模板自带的坑

模板出厂状态有四个已知问题，先知道再动手：

1. electron/main.ts 里没用的 require 声明会让 React / Vue / Vanilla 三种模板首次 npm run build 都报 TS6133；
2. electron-builder.json5 的 appId / productName 还是 YourAppName 占位符；
3. .gitignore 缺 dist-electron/ 和 release/（脚手架自带的自动补丁因 CRLF 行尾静默失效）；
4. 打包阶段要下载 electron 二进制，GitHub 直连不稳会失败。

这四个问题的原理和具体修法，展开在姊妹篇：《create-electron-vite 四个 build 坑与统一修复》。

接入 AI 编程

用 ZCode、Claude Code 这类 agent 型 CLI 直接打开项目目录，即可开始编程：

cd <项目名>
zcode        # 或 claude

注意：脚手架不会初始化 git（0.7.1 实测只生成 .gitignore 文件，仓库要自己建）。所以打开后的第一件事，让 AI 把版本管理基线建好：

初始化 git 仓库，把 .gitignore 补上 dist-electron/ 和 release/，然后完成首次提交。

有了首次提交做基线，之后 AI 的每一轮改动都能 diff、能回退——这是放心让 AI 大改的前提。

版本备查

我们对 Electron 桌面应用开发非常有经验——文中这些坑都亲自踩过、修平过。如果你正打算做一个桌面应用，欢迎聊聊。