package.json 与脚本配置
本教程共 45 篇 · 第 5 篇 · 更新于 2026-08-03
5. package.json 与脚本配置
本节目标
- 理解 main 字段如何指定主进程入口。
- 配置 scripts.start 用 electron . 启动应用。
- 区分 dependencies 与 devDependencies，及 Electron 为何属开发依赖。
- 学会锁定 Electron 版本，避免大版本漂移。
- 对比 Electron 项目与纯前端 package.json 的差异。
package.json 是任何 Node 项目的身份证，对 Electron 来说更是入口说明书。本章讲清几个关键字段，以及它和纯前端项目的区别。理解这些，你的项目才”可被 Electron 识别”。
5-1 main 字段：应用的真正入口
main 字段告诉 Electron 主进程文件在哪。如果省略，Electron 会默认找 index.js。但显式写出来永远是好习惯。
{
"main": "main.js"
}Electron 启动后，先读这个文件，执行里面的 app 逻辑，再由它创建窗口。所以 main.js 里至少要引入 app 与 BrowserWindow，并监听 whenReady。
提示：若你用 TypeScript 或打包工具，main 应指向编译后的产物，比如 dist/main.js，而不是源码 src/main.ts。
5-2 scripts：定义启动命令
scripts 是一组可命名的命令。跑 npm start 时，Electron 执行 electron .，那个 . 表示”在当前目录找 main 字段”。
{
"scripts": {
"start": "electron ."
}
}你也可以加别的脚本，比如 npm run dev 配合热重载工具。但 start 是约定俗成的开发启动入口，建议保留。
# 启动开发模式
npm start注意 electron . 只在开发时用。打包成安装包后，用户双击图标启动，不再经过这个命令。
5-3 dependencies 与 devDependencies
依赖分两类。dependencies 是运行时需要的包，会打进最终产物。devDependencies 只在开发期用，比如 Electron 本身、打包工具、测试库。
Electron 放在 devDependencies，原因前面提过：它的接口最终绑定到二进制，打包步骤会把这个二进制一起封进安装包，运行时不靠 npm 拉取。
{
"devDependencies": {
"electron": "^43.2.0"
}
}如果你的渲染进程用到了 React、lodash 这类运行时库，通常放在 dependencies。但现代前端多用打包工具，把它们一起打进页面，未必需要列在 dependencies。
5-4 Electron 版本怎么锁
^43.2.0 表示允许安装 43.x 的补丁和小版本，但不跨大版本。对 Electron 来说，锁定大版本很重要，因为大版本会升级 Chromium 和 Node，可能带来破坏性变更。
{
"devDependencies": {
"electron": "43.2.0"
}
}想要完全可复现的构建，可以把版本写死成 43.2.0，去掉 ^。团队项目建议这么做，避免不同人装到不同补丁版，调试时互相看不出差异。
查看当前锁定的版本：
npm ls electron这条命令打印项目里 Electron 的实际安装版本，排查”别人能跑我不能跑”时很有用。
5-5 和纯前端 package.json 的区别
纯前端项目的 main 通常是 index.js 入口模块，靠 npm run dev 起开发服务器，最后部署到网页托管。Electron 项目则把 main 指向主进程，靠 electron . 拉起桌面窗口。
| 字段 | 纯前端项目 | Electron 项目 |
|---|---|---|
| main | 库入口或忽略 | 主进程文件（必填） |
| scripts.start | 起 dev server | electron . 启动桌面 |
| 运行环境 | 浏览器 | Chromium + Node.js |
| 产物 | 静态资源 | 安装包 |
另一个区别是 Electron 项目几乎一定会把 Electron 写进 devDependencies，而纯前端项目没有这个依赖。
5-6 一个完整的最小示例
把前面几节拼起来，一个干净的最小 package.json 长这样：
{
"name": "my-electron-app",
"version": "1.0.0",
"description": "Electron 最小示例",
"main": "main.js",
"scripts": {
"start": "electron ."
},
"author": "码上学",
"license": "MIT",
"devDependencies": {
"electron": "43.2.0"
}
}加上 main.js、preload.js、index.html，四个文件凑齐，项目结构就完整了。后续接上打包工具时，这里还会冒出 build、forge.config.js 等字段。
5-7 别忘了 .gitignore
node_modules 体积很大，不该提交进 Git。把 GitHub 的 Node.js 模板 .gitignore 放进项目根目录，能避免误提交依赖。
# 典型的忽略项
echo "node_modules/" >> .gitignore
echo "dist/" >> .gitignore
echo "out/" >> .gitignore打包产物目录（如 dist、out）也建议忽略，它们可由构建命令重新生成。
5-8 用 npm scripts 串起开发流程
除了 start，你还可以加更多脚本把常用操作固化下来。比如用 electron . --debug 带调试参数启动，或接一个打包命令。
{
"scripts": {
"start": "electron .",
"dev": "electron . --enable-logging"
}
}脚本的本质就是一段 shell 命令的别名，能大幅降低团队新人的上手成本。但注意 start 是约定入口，保持它指向 electron . 最稳妥。
5-9 版本号字段与产物信息
package.json 顶层的 name、version、description、author 看似普通，打包成安装包后它们会变成窗口标题、关于面板、安装器显示的信息。
{
"name": "my-electron-app",
"version": "1.0.0",
"description": "我的第一个桌面应用",
"author": "码上学"
}所以这些字段别随手填。版本号建议遵循语义化版本（主.次.补丁），方便后续自动更新判断是否需要升级。
5-10 依赖与打包体积的关系
你可能会担心 devDependencies 里的 Electron 会让安装包巨大。其实打包工具（如 Electron Forge）只会把运行必需的二进制和你的代码打进去，开发期的一大堆依赖不会全进安装包。
但渲染进程用到的运行时库，若没经打包工具处理，确实会变大。所以前端代码建议用 webpack、Vite 这类工具先打包压缩，再交给 Electron 加载，能明显减小体积、提升启动速度。
理解 dependencies 与 devDependencies 的分工，有助于你判断”这个包该不该打进产物”。规则很简单：只在构建或开发时用，放 devDependencies；运行时真要用到，才放 dependencies。
5-11 name 字段的命名约束
name 字段看着随意，却有几条硬规则。它必须全小写，不能含空格，只能用连字符、下划线或点。大写或空格会在发布时报错。
{
"name": "my-electron-app"
}这个名字会进入安装包标识，建议和你的产品名保持一致，只是转成小写连字符形式。改名要慎重，因为它关联到自动更新时的应用身份，中途改名字可能让老用户更新失败。
5-12 锁文件的作用
npm install 时会生成 package-lock.json，它精确记录了每个依赖装的是哪个版本。有了它，别人 npm ci 装到的依赖和你完全一致，避免”在我机器上能跑”的问题。
# 用锁文件精确安装，适合 CI 和生产
npm ci注意 npm ci 会先删掉 node_modules 再按锁文件重建，比 npm install 更可复现。提交代码时记得把 package-lock.json 一起提交，别把它加进 .gitignore。
当 Electron 版本需要升级，改 package.json 里那一行再 npm install，锁文件会自动更新。团队里谁升级了版本，其他人拉下来就能同步，减少环境分歧。
5-13 本章小结
package.json 里 main 指向主进程，scripts.start 用 electron . 启动，Electron 锁在 devDependencies 并尽量固定大版本。它和纯前端项目的关键差异在于入口与运行环境。
下一章进入应用生命周期，看 app 模块如何掌管启动、激活与退出。