electron-publish-cli

ep 是配置驱动的 Electron 构建与 Release 管理工具，由“极光笔记”原有的版本升级、产物校验、GitHub/Gitee 发布脚本抽离而来。

工具使用 Node.js 18.11+ 内置能力，没有运行时 npm 依赖。它只在使用者主动执行命令时运行项目已有的 npm 子脚本，不安装依赖，也不替项目决定 electron-builder 的平台配置。

全局安装

CLI 不需要加入 Electron 项目的 dependencies 或 devDependencies。由使用者按需手动全局安装：

npm install --global D:\my_project\front-sdk\electron-publish-cli

安装后直接在 Electron 项目目录调用全局 ep，不需要在 package.json 中增加包装脚本：

ep build
ep check github
ep release github
ep release github --retry

CLI 会调用当前项目本地安装的 Vite 和 electron-builder；在 Windows 上直接读取依赖包声明的 Node 入口，避免 .cmd 在中文或空格路径下出现引号解析错误。打包时会动态注入 CLI 自身的 afterPack 钩子，项目不需要配置 CLI 的安装路径。依赖安装、构建和发布命令均由使用者按需手动执行。

命令

| 命令 | 功能 | | --- | --- | | ep init | 生成缺失的配置、私密配置示例和 CHANGELOG | | ep bump [patch\|minor\|major\|版本号] | 同步更新 package.json 与 package-lock.json | | ep build | 渲染构建、版本升级、旧输出清理、Electron 打包 | | ep check [github\|gitee] | 本地校验当前版本发布产物，不访问网络 | | ep release github | 构建并发布 GitHub Release | | ep release gitee | 构建并发布 Gitee Release | | ep release <平台> --retry | 跳过构建并恢复未完成发布；GitHub 仅允许复用未公开草稿 | | ep release <平台> --skip-build | 跳过构建，发布当前版本已有产物 |

通用选项：

• -p, --project <path>：Electron 项目目录。
• -c, --config <file>：项目内配置文件，默认 electron-publish.config.json。
• --profile <name>：使用配置中的构建 profile。
• --no-bump：构建时保留当前版本号。

项目配置

完整示例见 electron-publish.config.example.json。关键字段：

{
  "productName": "示例应用",
  "credentialsFile": ".electron-publish.secrets.json",
  "artifact": {
    "outputDirectory": "release/${version}",
    "setupFile": "${productName}-Windows-${version}-Setup.exe",
    "metadataFile": "latest.yml",
    "includeBlockmap": true
  },
  "build": {
    "rendererCommand": ["vite", "build"],
    "builderCommand": ["electron-builder", "--publish", "never"],
    "bump": "patch",
    "cleanOldVersions": true,
    "environment": {},
    "profiles": {}
  },
  "providers": {
    "github": {
      "repository": "https://github.com/owner/repository.git",
      "tokenKey": "github"
    }
  }
}

artifact.outputDirectory 必须包含 ${version}，CLI 才能将删除范围严格限制在版本输出目录中。

GitHub 发布始终按 .blockmap → 安装包 → latest.yml 上传，随后校验远端附件的 状态、大小和可用的 SHA-256 摘要，校验通过后立即请求公开草稿，不再额外等待。 旧配置中的 assetSettleSeconds 已停用，保留也不会产生延时，可以直接删除。

附件上传完成不代表发布完成。出现“GitHub 发布完成”和“发布流程已结束，可以关闭命令行窗口” 后即可关闭窗口；在校验或公开草稿期间请保持窗口开启。若在公开草稿前中断， 可执行 ep release github --retry 跳过构建并重新上传草稿附件、校验和发布。

已经公开的 GitHub Release 被视为不可变，--retry 只能恢复同标签的未公开草稿。 需要修正已公开产物时应升级版本并创建新 Release，避免在线客户端读取到混合附件。 Gitee 不支持相同的草稿流程，因此 --retry 只补传缺失附件并校验已有附件， 不会覆盖已经对客户端可见的同名文件。

凭据

令牌按以下优先级读取：

1. provider 的 token 配置（兼容旧配置，不推荐）。
2. credentialsFile 指定的本地 JSON 文件，读取 provider 的 tokenKey。

本地私密文件示例：

{
  "github": "your-github-token",
  "gitee": "your-gitee-token"
}

生产项目应只使用被 Git 忽略的 .electron-publish.secrets.json，不要把令牌写进 electron-publish.config.json 或提交到 Git 历史。