Electron Fiddle 贡献指南：从源码运行、编写测试到发布新版本的完整实践

• 桌面应用
• 开发工具
• 代码编辑器

Electron Fiddle 是一个由社区驱动的 Electron 实验与学习工具，你可以在其中快速创建小型 Electron 应用、切换不同 Electron 版本运行，并以 GitHub Gist 或本地目录的形式保存分享。本文以仓库根目录的 CONTRIBUTING.md 为核心骨架，结合package.json、tools/下的构建脚本、.github/workflows/下的 CI 与发布流水线等源码证据，系统讲解如何为该项目贡献代码：从环境准备、从源码启动 Fiddle、运行与编写测试，到提交符合规范的 Pull Request，直至参与版本发布的全过程。读完本文，你将掌握一套可直接照做的开源贡献实战流程。

项目定位与贡献方式

Electron Fiddle 是一个社区驱动（community-driven）的开源项目，由 Electron 生态工作组（Electron Ecosystem Working Group）监督。这意味着项目欢迎并鼓励各类贡献，官方列出的贡献类型包括但不限于：

• 建设性反馈（Constructive feedback）
• Bug 报告 / 技术问题（Bug reports / technical issues）
• 文档改进（Documentation changes）
• 功能请求（Feature requests）
• Pull Requests

官方强烈建议：在提交 issue 之前，先搜索已有 issue，确认该问题是否已被他人提交过，避免重复劳动。作为 Electron 生态的一部分，本项目的所有贡献同样遵循 Electron 的 code of conduct。

对于想从零开始参与的新手，项目在 issue 跟踪器中维护了good first issue标签，用来标记范围界定清晰、适合社区成员接手的 Bug 或功能请求。如果这类 issue 信息不足，可以放心地在上面提出建设性问题（这一点对所有打开的 issue 都适用）。

环境准备：从源码运行 Electron Fiddle

贡献代码的第一步，是把项目跑起来。官方给出的从源码运行流程共四步：

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/fi/fiddle.git # 2. 进入项目目录 cd fiddle # 3. 安装依赖 yarn # 4. 启动 Fiddle 并开始探索 yarn start

结合 package.json 可以还原这条命令背后的更多细节，帮助你判断本地环境是否达标：

• Node 版本：engines字段声明node >= 22.12.0；仓库根目录的 .nvmrc 固定为22.17，建议用 nvm 切换到此版本后安装依赖。
• 包管理器：packageManager字段声明yarn@4.10.3，是 Yarn 4（Berry），安装依赖请统一使用yarn而非npm。
• yarn安装依赖时会触发postinstall脚本：它由husky && npm run electron-releases组成——前者安装 git hooks（配合lint-staged在提交时自动执行代码检查），后者调用 tools/fetch-releases.ts 从上游拉取 Electron 版本信息写入static/releases.json，供 Fiddle 内的版本选择器使用。如果离线环境拉取失败，该脚本在非 CI 环境下会回退使用磁盘上已有的文件（见 tools/fetch-releases.ts）。
• yarn start的真实执行链：start脚本定义为tsx ./tools/clean-webpack.ts && electron-forge start --。它会先用 tools/clean-webpack.ts 删除上一次构建残留的.webpack目录，再通过 Electron Forge 以 webpack 插件启动开发模式。入口配置见 forge.config.ts：主进程入口是 src/main/main.ts，渲染进程窗口对应 static/index.html 与 src/renderer/main.tsx，另有独立的isolated_run_button入口。

运行测试：yarn test与FIDDLE_VERBOSE_TESTS

项目测试命令非常简单：

yarn test

但这条命令背后藏着一个值得注意的实现：test脚本定义为tsx ./tools/vitest.ts run，而 tools/vitest.ts 并不是直接调用 vitest 的 CLI，而是以ELECTRON_RUN_AS_NODE=1的方式用项目自带的 Electron 可执行文件去运行 vitest。这样测试运行时的 Node 环境与 Fiddle 实际运行环境保持一致，属于 Electron 项目的常见做法。

测试的配置集中在一个文件里：

• 运行环境：jsdom；
• 用例匹配：**/tests/**/*.spec.{ts,tsx}；
• 启动钩子：tests/globalSetup.ts 在跑测试前并行执行maybeFetchContributors与populateReleases，预取贡献者名单与 Electron 版本数据；
• 每文件钩子：tests/setup.ts 负责初始化各种 mock。

FIDDLE_VERBOSE_TESTS：让测试输出可见

CONTRIBUTING.md 特别提醒：测试期间console.log()等控制台调用会被 mock 掉，以避免测试报告里的噪音。如果希望保留这些输出——比如正在调试或编写新测试时——可以通过设置环境变量FIDDLE_VERBOSE_TESTS来开启：

FIDDLE_VERBOSE_TESTS=1 yarn test

这个行为的实现就在 tests/setup.ts：当环境变量未设置时，用vi.spyOn将console.error/info/log/warn/debug全部替换为空实现；一旦设置了FIDDLE_VERBOSE_TESTS，这些 console 调用保持真实输出。同一文件中还 mock 了electron、fs-extra、@sentry/electron/*等外部依赖，并提供了window.ElectronFiddle、window.monaco、window.app等全局对象（见 tests/mocks/mocks.ts），这是理解测试用例如何隔离外部副作用的关键。

与 CI 中测试的差异

本地yarn test与 CI 略有不同。在 .github/workflows/test.yml 中，CI 会先执行yarn run lint && yarn run format，再执行yarn tsc && yarn test:ci。其中test:ci定义为：

tsx ./tools/vitest.ts run --coverage --reporter=default --reporter=junit --outputFile=./reports/report.xml

它额外开启了覆盖率统计与 JUnit 报告输出。这套 CI 测试矩阵覆盖macos-15-intel、ubuntu-latest、windows-latest（x64），并额外包含 macOS arm64 与 Ubuntu armv7l 两个架构，保证跨平台兼容性。

提交 Pull Request 的规范

修复 Bug、新增功能等代码贡献主要通过 Pull Request 完成。CONTRIBUTING.md 明确了几条硬性要求：

1. 先了解 Git 协作基础：如果不熟悉 fork、branch 与 PR 流程，建议先查阅 GitHub 官方的协作文档再动手。
2. CI 自动把关：项目使用 GitHub Actions 对每个新提交执行检查，确保代码符合风格规范（lint）且测试套件全部通过。也就是说，你的 PR 提交后会被自动构建与测试，无需本地等待。
3. 尽量编写测试：除非不切实际，请为你的改动补上测试，这能让维护者更容易发现回归问题。
4. 遵循 Conventional Commits：commit message 与 PR 标题必须符合 conventional commits 中的amannn/action-semantic-pull-request自动校验每个 PR 标题是否合规。
5. 不要自行升级版本号：请勿在 PR 中 bumppackage.json的version字段，版本号的调整由维护者负责。你可以在 PR 描述中说明改动属于 major、minor 还是 patch 级别，以便维护者按语义化版本规范处理。

本地检查清单

在推送 PR 前，可以在本地先跑一遍与 CI 等价的质量检查。lint脚本实际是npm-run-all "lint:!(fix)"，包含四个子项：

• lint:js：oxlint，检查 JS/TS 代码；
• lint:style：stylelint，检查src/less/*.less样式；
• lint:markdown：markdownlint-cli2 "*.md"，检查 Markdown 文档；
• lint:links：lint-roller-markdown-links "*.md"，检查文档中的仓库内链接有效性。

另外format用 Prettier 校验src与static/**/*.js的格式。这些规则与 package.json 中定义的lint-staged配合：提交时被暂存的*.{js,ts,tsx}文件会自动执行lint:js --fix与 prettier 格式化，.less文件则执行 stylelint 修复。

Release 流程：从版本号到正式发布

注意：发布（Release）仅对拥有electron/fiddle仓库写权限的贡献者开放。普通贡献者的 PR 合入后，版本发布由维护者执行。

完整的发布路径如下：

1. 创建发布分支：为本次发布新建一个分支。
2. 执行版本升级命令：运行yarn version并携带对应的位置参数major、minor或patch，例如yarn version patch。该命令会生成一个更新了 package.json 中version字段的提交。
3. 打标签：用git tag为这个新版本号创建对应的 tag。
4. 合入主分支：把版本号变更的提交提交到 main 分支，推送后打开一个 Pull Request。
5. 推送标签触发 CI 发布：git push origin <tag_name>推送 tag 后，CI 会自动起草（draft）一个新的 Release。

从 .github/workflows/release.yml 可以看到这个自动化过程的全貌：工作流以push: tags: - 'v*'为触发条件，即任何v开头的 tag 都会触发构建矩阵——macOS/Linux/Windows 各架构并行执行yarn run publish --arch=... --dry-run（dry-run 只产出产物不真正发布），Windows 侧还通过 Azure Trusted Signing 对安装包做代码签名。各平台产物上传为 artifacts 后，release任务汇总这些产物，最终执行yarn run publish --from-dry-run发布到 GitHub Releases，并额外把 webpack source maps 上传至 Sentry 用于生产环境错误定位。

发布目标的配置在 forge.config.ts：使用@electron-forge/publisher-github，仓库为electron/fiddle，关键参数是draft: true（先创建草稿 Release）、prerelease: false（标记为正式版本）与generateReleaseNotes: true（自动生成 release notes）。

发布前的人工检查清单（来自 CONTRIBUTING.md）：检查 Release 中所有预期文件是否齐全、安装包能否正常工作，确认无误后再正式发布。

构建与打包相关补充

除了日常开发与测试，forge.config.ts 还定义了完整的打包链路，理解它对参与构建类 PR 会有帮助：

• yarn make：electron-forge make，产出各平台安装包。CI 中的 build.yml 即用它生成未签名产物。
• yarn package：electron-forge package，仅打包为可运行的应用目录。
• yarn publish：electron-forge publish，发布产物。
• 支持的安装包格式：Windows 的 Squirrel（exe）与 MSIX、macOS 的 zip、Linux 的 deb / rpm / AppImage（见 forge.config.ts）。
• yarn electron-releases/yarn contributors：分别刷新static/releases.json与贡献者数据；contributors脚本（tools/contributors.ts）会调用 GitHub API 拉取贡献者列表并过滤掉 Bot 与贡献次数不足 2 次的账号（见 tools/contributors.ts），因此 CI 中执行它时需要注入GITHUB_TOKEN。

小结

为 Electron Fiddle 贡献代码的完整链路可以概括为：搜索已有 issue 避免重复 → 认领good first issue或自报问题 → 按 Conventional Commits 规范提交 → 补写测试并通过yarn test（必要时用FIDDLE_VERBOSE_TESTS查看输出）→ 本地跑通 lint/format/tsc → 发起 PR 等待 CI 验证 → 合入后由维护者按语义化版本规则执行yarn version+ tag 发布流程。无论你是提交第一个 Bug 修复的新手，还是准备参与版本发布的维护者，本文梳理的命令、配置与源码证据都已覆盖官方指南的全部要点，可以作为一份随时查阅的实战手册。

• 桌面应用
• 开发工具
• 代码编辑器