Kap 项目维护与版本发布实战指南从日常开发到 Stable / Beta 双轨道 Release 流程【免费下载链接】KapAn open-source screen recorder built with web technology项目地址: https://gitcode.com/gh_mirrors/ka/Kap本文基于仓库根目录的 maintaining.md系统讲解开源屏幕录制应用 Kap 的日常开发、代码质量保障以及基于 GitHub Releases 与 CircleCI 的正式版 / Beta 版双轨道发布流程。读完本文你将掌握 Kap 的 watch 模式开发命令、lint 与测试门禁的使用方式并能按规范完成从「打版本号」到「发布 Release」的完整维护操作。一、为什么需要一份「维护手册」Kap 是一个用 Web 技术构建的开源屏幕录制工具Electron Next.js TypeScript其仓库同时包含主进程main/、渲染进程renderer/、插件体系main/plugins/与测试套件test/。对一个有真实用户、依赖 CI 自动出包的开源项目而言maintaining.md承担着三件事让贡献者能快速跑起本地开发环境、让维护者能按统一节奏发布正式版、让预发布版本可以安全地走独立分支通道。本文即围绕这三个目标展开并在关键步骤上补充仓库源码级的证据。二、日常开发双终端启动 watch 模式maintaining.md给出的开发姿势非常简单核心是「两个终端、两条命令」终端 A 运行yarn dev启动 Next.js 的 watch 模式监听渲染进程renderer代码变更并热重载。终端 B 运行yarn start编译主进程并启动 Electron 应用本体。对照 package.json 中声明的 scripts可以看到这两条命令背后的真实行为dev: next dev renderer只对renderer目录启动 Next.js 开发服务器实现渲染层热更新。start: tsc run-electron .先通过 TypeScript 编译器把main/下的 TS 源码编译到dist-js/再借助run-electron启动 Electron入口为main: dist-js/index.js。值得注意的是yarn start中的tsc是一次性编译而非增量 watch因此常规做法就是让渲染层走yarn dev的热更新、主进程改动后再手动重启yarn start这与维护手册推荐的双终端方案完全吻合。如果只是验证打包产物是否可用contributing.md还提供了另一种方式$ yarn run pack它会先执行yarn buildtscnext build renderer next export renderer再用electron-builder --dir生成未打包成安装镜像的应用目录产物位于dist目录适合在发布前快速自测。依赖安装与首次启动进入仓库后首先执行$ yarnpostinstall钩子会自动执行electron-builder install-app-deps确保 Electron 原生依赖与当前 Electron 版本匹配。首次启动前建议先跑一遍测试与 lint确认环境干净。三、代码规范XO 与 Stylelint 的编辑器集成maintaining.md特别强调强烈建议为编辑器安装两类插件XO 编辑器插件负责 JavaScript / TypeScript 代码风格检查Kap 采用 xo 风格即 2 空格缩进、无分号风格等。Stylelint 编辑器插件负责 CSS 样式检查。两者的共同优势是支持auto-fix on save保存时自动修复把格式化工作完全交给工具贡献者无需手动调整风格。仓库中package.json的xo字段配置了完整的规则集extends: xo-react并对 JS/JSX 使用babel-eslint解析器、对 TS/TSX 叠加xo-typescript规则同时通过overrides为test/**/*.ts放行了断言相关的规则。也就是说编辑器内出现的告警与 CI 里跑yarn lint的结果是同一套标准。四、提交与 CI 的质量门禁lint 单元测试Kap 在提交和推送两个时机都设置了自动门禁见 package.jsonpre-commit钩子yarn lintpre-push钩子yarn lint这意味着任何未通过 XO 检查的代码都无法正常提交或推送。除了 lint测试也是发布前的硬性要求仓库提供了两套测试命令# 本地运行全部检查lint 单测 $ yarn test # 只跑主进程单元测试 $ yarn test:main # CI 专用输出 TAP 格式并由 tap-xunit 转为 JUnit XML $ yarn test:ci测试运行器是 AVA配置见 package.json扫描test/**/*.ts、test/**/*.js排除test/helpers与test/mocks使用ts-node转译默认超时 5 分钟、failFast开启。从仓库可见的真实测试文件包括 test/convert.ts转换流程、test/recording-history.ts录制历史等均依赖 test/mocks 下的 Electron、插件、设置等 mock 实现保证单测可在无真实窗口环境下运行。五、发布正式版Stable的标准流程maintaining.md给出了完整、可全程在 GitHub 网页上完成的正式版发布步骤。结合仓库内容其本质是一条「手动打版本号 → CI 自动构建 → 人工确认发布」的流水线。按顺序展开如下1. 创建 Release 草稿进入仓库的 Releases 页面点击Draft a new release。在Tag version字段写入带v前缀的新版本号例如v2.0.0当前仓库版本见 package.json为3.6.0。Release title留空Release 标题会自动取 Tag 名。编写发布说明Release notes建议列出本次的功能、修复与破坏性变更。点击Save draft保存为草稿。2. 更新版本号并提交将 package.json 中的version字段改为新版本号例如2.0.0注意此时不带v前缀前缀只用于 Git Tag。使用版本号本身作为 commit 标题提交例如2.0.0。这样 Git 历史里每一次提交标题就是一个明确的发布版本号方便回溯。3. 等待 CircleCI 构建出包提交推送到main分支后CircleCI 会自动执行构建编译主进程、导出渲染层、跑测试并通过 electron-builder 生成安装包与更新源。构建产物会被自动挂载到第 1 步创建的 Release 草稿上。Kap 的正式包针对 macOS 双架构输出见 package.json 中build.mac.target.arch: [x64, arm64]安装包命名规则为${productName}-${version}-${arch}.${ext}并配置了electron-builder-notarize的afterSign公证步骤保证产物可以通过 macOS Gatekeeper。4. 发布确认二进制已挂载到草稿后点击草稿的Edit再点击Publish release正式版即对外发布。提示正式版发布全流程强调「先 Save draft、再等 CI、最后 Publish」其用意是确保任何人下载到的 Release 一定带有构建产物避免出现「有版本号却没安装包」的残缺发布。六、发布 Beta 版独立分支 预发布标记预发布版本走的是与正式版完全隔离的beta分支避免污染main的发布历史。步骤如下1. 同步 beta 分支# 切到 beta 分支 $ git checkout beta # 从 main 变基确保 beta 基于最新主线代码 $ git pull --rebase origin main使用--rebase而非 merge是为了让 beta 分支保持线性历史便于后续维护与回溯。2. 修改版本号并写入「Beta build customizations」提交修改 package.json 中的version例如2.0.0-beta.3。仓库约定beta 相关定制包括版本号改动统一收进一个名为 Beta build customizations 的提交中。因此执行# 暂存全部改动并追加到该提交 $ git add . git commit --amend--amend会把本次版本号改动合并进既有的定制提交保持 beta 分支上「功能提交」与「发布定制」清晰分离。3. 强制推送并打 Tag# 因为重写了历史需要 force push $ git push --force # 以 package.json 中的版本号打 annotated tag 并推送 $ git tag -a v2.0.0-beta.3 -m v2.0.0-beta.3 git push --follow-tagsTag 名同样带v前缀且与package.json的版本号严格一致--follow-tags会连同新打的 tag 一起推送。4. 等待 CI 并发布预发布版推送后 CircleCI 会自动构建并把二进制挂载到一个自动创建的 Release 草稿上。进入该草稿勾选This is a pre-release点击Publish release。预发布标记的意义在于正式用户不会在「Latest release」看到 Beta 版而愿意尝鲜的用户仍可显式下载这同时保证了正式版与 Beta 版可并行存在、互不干扰。七、发布流程背后的工程机制package.json 全链路把维护手册的步骤与仓库配置对照可以看到一条完整的「版本 → 构建 → 分发」链路阶段命令 / 配置位置版本号来源version: 3.6.0发布时手动修改package.json主进程编译build-main: tscpackage.json渲染层构建build-renderer: next build renderer next export rendererpackage.json全量构建build: yarn build-main yarn build-rendererpackage.json生成安装包dist: npm run build electron-builderpackage.jsonmacOS 打包双架构x64/arm64、notarize、DMG 布局package.json测试门禁AVA husky pre-commit/pre-pushpackage.json应用更新electron-updater依赖 electronUpdaterCompatibilitypackage.json从源码结构看CI 构建出的 dmg 安装包会同时作为 GitHub Releases 的附件README 也提到各分支的临时构建可通过https://kap-artifacts.now.sh/branch获取这说明版本发布的产物体系是「Release 正式分发 分支级临时构建」双层结构。八、维护者的日常反馈渠道与 Bug 报告模板除了发版维护者还需要持续接收用户反馈。仓库在应用菜单中内置了「Send Feedback…」入口见 main/menus/common.ts它调用openNewGitHubIssue打开一个新 Issue并预填一份结构化的 Bug 报告模板见 main/menus/common.ts内容包括macOS 版本通过macos-release工具将内核版本号映射为系统名称如 Ventura 13、Monterey 12 等映射表维护在 main/utils/macos-release.tsKap 版本app.getVersion()动态获取复现步骤 / 当前行为 / 期望行为 / 临时解决方案四段式结构。当应用内部发生未捕获异常时错误处理模块也会携带同样的上下文见 main/utils/errors.ts弹出反馈入口。这套机制保证无论用户手动反馈还是自动上报维护者拿到的都是「版本 系统 步骤」齐备的 Issue能大幅降低排查成本。九、维护流程小结与最佳实践回顾整个维护体系可以提炼出几条值得借鉴的实践开发与发布命令分离yarn dev/yarn start只管本地迭代yarn pack/yarn dist才产出可分发产物职责清晰。门禁前置lint 挂在pre-commit/pre-push单测纳入test与test:ci让 CI 只处理「已经过本地检查」的代码。正式版与 Beta 版双轨道main分支发布 Stablebeta分支含独立定制提交发布 pre-release历史互不干扰、可随时 rebase 同步主线。人机分工明确版本号与发布说明由维护者手动控制二进制构建与挂载交给 CircleCI最终由维护者确认 Publish——每个环节都有明确的责任人避免误发布。可追溯commit 标题、Git Tag 与package.json版本号三者严格一致配合 annotated tag任何版本都能快速对应到精确的代码快照。对希望为 Kap 提交代码或自行维护分叉的开发者建议完整阅读仓库内的 contributing.md贡献指南与 docs/plugins.md插件开发文档而上述维护与发布流程则全部以 maintaining.md 为准两者共同构成了 Kap 从「写代码」到「发版本」的完整闭环。【免费下载链接】KapAn open-source screen recorder built with web technology项目地址: https://gitcode.com/gh_mirrors/ka/Kap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Kap 项目维护与版本发布实战指南：从日常开发到 Stable / Beta 双轨道 Release 流程
Kap 项目维护与版本发布实战指南从日常开发到 Stable / Beta 双轨道 Release 流程【免费下载链接】KapAn open-source screen recorder built with web technology项目地址: https://gitcode.com/gh_mirrors/ka/Kap本文基于仓库根目录的 maintaining.md系统讲解开源屏幕录制应用 Kap 的日常开发、代码质量保障以及基于 GitHub Releases 与 CircleCI 的正式版 / Beta 版双轨道发布流程。读完本文你将掌握 Kap 的 watch 模式开发命令、lint 与测试门禁的使用方式并能按规范完成从「打版本号」到「发布 Release」的完整维护操作。一、为什么需要一份「维护手册」Kap 是一个用 Web 技术构建的开源屏幕录制工具Electron Next.js TypeScript其仓库同时包含主进程main/、渲染进程renderer/、插件体系main/plugins/与测试套件test/。对一个有真实用户、依赖 CI 自动出包的开源项目而言maintaining.md承担着三件事让贡献者能快速跑起本地开发环境、让维护者能按统一节奏发布正式版、让预发布版本可以安全地走独立分支通道。本文即围绕这三个目标展开并在关键步骤上补充仓库源码级的证据。二、日常开发双终端启动 watch 模式maintaining.md给出的开发姿势非常简单核心是「两个终端、两条命令」终端 A 运行yarn dev启动 Next.js 的 watch 模式监听渲染进程renderer代码变更并热重载。终端 B 运行yarn start编译主进程并启动 Electron 应用本体。对照 package.json 中声明的 scripts可以看到这两条命令背后的真实行为dev: next dev renderer只对renderer目录启动 Next.js 开发服务器实现渲染层热更新。start: tsc run-electron .先通过 TypeScript 编译器把main/下的 TS 源码编译到dist-js/再借助run-electron启动 Electron入口为main: dist-js/index.js。值得注意的是yarn start中的tsc是一次性编译而非增量 watch因此常规做法就是让渲染层走yarn dev的热更新、主进程改动后再手动重启yarn start这与维护手册推荐的双终端方案完全吻合。如果只是验证打包产物是否可用contributing.md还提供了另一种方式$ yarn run pack它会先执行yarn buildtscnext build renderer next export renderer再用electron-builder --dir生成未打包成安装镜像的应用目录产物位于dist目录适合在发布前快速自测。依赖安装与首次启动进入仓库后首先执行$ yarnpostinstall钩子会自动执行electron-builder install-app-deps确保 Electron 原生依赖与当前 Electron 版本匹配。首次启动前建议先跑一遍测试与 lint确认环境干净。三、代码规范XO 与 Stylelint 的编辑器集成maintaining.md特别强调强烈建议为编辑器安装两类插件XO 编辑器插件负责 JavaScript / TypeScript 代码风格检查Kap 采用 xo 风格即 2 空格缩进、无分号风格等。Stylelint 编辑器插件负责 CSS 样式检查。两者的共同优势是支持auto-fix on save保存时自动修复把格式化工作完全交给工具贡献者无需手动调整风格。仓库中package.json的xo字段配置了完整的规则集extends: xo-react并对 JS/JSX 使用babel-eslint解析器、对 TS/TSX 叠加xo-typescript规则同时通过overrides为test/**/*.ts放行了断言相关的规则。也就是说编辑器内出现的告警与 CI 里跑yarn lint的结果是同一套标准。四、提交与 CI 的质量门禁lint 单元测试Kap 在提交和推送两个时机都设置了自动门禁见 package.jsonpre-commit钩子yarn lintpre-push钩子yarn lint这意味着任何未通过 XO 检查的代码都无法正常提交或推送。除了 lint测试也是发布前的硬性要求仓库提供了两套测试命令# 本地运行全部检查lint 单测 $ yarn test # 只跑主进程单元测试 $ yarn test:main # CI 专用输出 TAP 格式并由 tap-xunit 转为 JUnit XML $ yarn test:ci测试运行器是 AVA配置见 package.json扫描test/**/*.ts、test/**/*.js排除test/helpers与test/mocks使用ts-node转译默认超时 5 分钟、failFast开启。从仓库可见的真实测试文件包括 test/convert.ts转换流程、test/recording-history.ts录制历史等均依赖 test/mocks 下的 Electron、插件、设置等 mock 实现保证单测可在无真实窗口环境下运行。五、发布正式版Stable的标准流程maintaining.md给出了完整、可全程在 GitHub 网页上完成的正式版发布步骤。结合仓库内容其本质是一条「手动打版本号 → CI 自动构建 → 人工确认发布」的流水线。按顺序展开如下1. 创建 Release 草稿进入仓库的 Releases 页面点击Draft a new release。在Tag version字段写入带v前缀的新版本号例如v2.0.0当前仓库版本见 package.json为3.6.0。Release title留空Release 标题会自动取 Tag 名。编写发布说明Release notes建议列出本次的功能、修复与破坏性变更。点击Save draft保存为草稿。2. 更新版本号并提交将 package.json 中的version字段改为新版本号例如2.0.0注意此时不带v前缀前缀只用于 Git Tag。使用版本号本身作为 commit 标题提交例如2.0.0。这样 Git 历史里每一次提交标题就是一个明确的发布版本号方便回溯。3. 等待 CircleCI 构建出包提交推送到main分支后CircleCI 会自动执行构建编译主进程、导出渲染层、跑测试并通过 electron-builder 生成安装包与更新源。构建产物会被自动挂载到第 1 步创建的 Release 草稿上。Kap 的正式包针对 macOS 双架构输出见 package.json 中build.mac.target.arch: [x64, arm64]安装包命名规则为${productName}-${version}-${arch}.${ext}并配置了electron-builder-notarize的afterSign公证步骤保证产物可以通过 macOS Gatekeeper。4. 发布确认二进制已挂载到草稿后点击草稿的Edit再点击Publish release正式版即对外发布。提示正式版发布全流程强调「先 Save draft、再等 CI、最后 Publish」其用意是确保任何人下载到的 Release 一定带有构建产物避免出现「有版本号却没安装包」的残缺发布。六、发布 Beta 版独立分支 预发布标记预发布版本走的是与正式版完全隔离的beta分支避免污染main的发布历史。步骤如下1. 同步 beta 分支# 切到 beta 分支 $ git checkout beta # 从 main 变基确保 beta 基于最新主线代码 $ git pull --rebase origin main使用--rebase而非 merge是为了让 beta 分支保持线性历史便于后续维护与回溯。2. 修改版本号并写入「Beta build customizations」提交修改 package.json 中的version例如2.0.0-beta.3。仓库约定beta 相关定制包括版本号改动统一收进一个名为 Beta build customizations 的提交中。因此执行# 暂存全部改动并追加到该提交 $ git add . git commit --amend--amend会把本次版本号改动合并进既有的定制提交保持 beta 分支上「功能提交」与「发布定制」清晰分离。3. 强制推送并打 Tag# 因为重写了历史需要 force push $ git push --force # 以 package.json 中的版本号打 annotated tag 并推送 $ git tag -a v2.0.0-beta.3 -m v2.0.0-beta.3 git push --follow-tagsTag 名同样带v前缀且与package.json的版本号严格一致--follow-tags会连同新打的 tag 一起推送。4. 等待 CI 并发布预发布版推送后 CircleCI 会自动构建并把二进制挂载到一个自动创建的 Release 草稿上。进入该草稿勾选This is a pre-release点击Publish release。预发布标记的意义在于正式用户不会在「Latest release」看到 Beta 版而愿意尝鲜的用户仍可显式下载这同时保证了正式版与 Beta 版可并行存在、互不干扰。七、发布流程背后的工程机制package.json 全链路把维护手册的步骤与仓库配置对照可以看到一条完整的「版本 → 构建 → 分发」链路阶段命令 / 配置位置版本号来源version: 3.6.0发布时手动修改package.json主进程编译build-main: tscpackage.json渲染层构建build-renderer: next build renderer next export rendererpackage.json全量构建build: yarn build-main yarn build-rendererpackage.json生成安装包dist: npm run build electron-builderpackage.jsonmacOS 打包双架构x64/arm64、notarize、DMG 布局package.json测试门禁AVA husky pre-commit/pre-pushpackage.json应用更新electron-updater依赖 electronUpdaterCompatibilitypackage.json从源码结构看CI 构建出的 dmg 安装包会同时作为 GitHub Releases 的附件README 也提到各分支的临时构建可通过https://kap-artifacts.now.sh/branch获取这说明版本发布的产物体系是「Release 正式分发 分支级临时构建」双层结构。八、维护者的日常反馈渠道与 Bug 报告模板除了发版维护者还需要持续接收用户反馈。仓库在应用菜单中内置了「Send Feedback…」入口见 main/menus/common.ts它调用openNewGitHubIssue打开一个新 Issue并预填一份结构化的 Bug 报告模板见 main/menus/common.ts内容包括macOS 版本通过macos-release工具将内核版本号映射为系统名称如 Ventura 13、Monterey 12 等映射表维护在 main/utils/macos-release.tsKap 版本app.getVersion()动态获取复现步骤 / 当前行为 / 期望行为 / 临时解决方案四段式结构。当应用内部发生未捕获异常时错误处理模块也会携带同样的上下文见 main/utils/errors.ts弹出反馈入口。这套机制保证无论用户手动反馈还是自动上报维护者拿到的都是「版本 系统 步骤」齐备的 Issue能大幅降低排查成本。九、维护流程小结与最佳实践回顾整个维护体系可以提炼出几条值得借鉴的实践开发与发布命令分离yarn dev/yarn start只管本地迭代yarn pack/yarn dist才产出可分发产物职责清晰。门禁前置lint 挂在pre-commit/pre-push单测纳入test与test:ci让 CI 只处理「已经过本地检查」的代码。正式版与 Beta 版双轨道main分支发布 Stablebeta分支含独立定制提交发布 pre-release历史互不干扰、可随时 rebase 同步主线。人机分工明确版本号与发布说明由维护者手动控制二进制构建与挂载交给 CircleCI最终由维护者确认 Publish——每个环节都有明确的责任人避免误发布。可追溯commit 标题、Git Tag 与package.json版本号三者严格一致配合 annotated tag任何版本都能快速对应到精确的代码快照。对希望为 Kap 提交代码或自行维护分叉的开发者建议完整阅读仓库内的 contributing.md贡献指南与 docs/plugins.md插件开发文档而上述维护与发布流程则全部以 maintaining.md 为准两者共同构成了 Kap 从「写代码」到「发版本」的完整闭环。【免费下载链接】KapAn open-source screen recorder built with web technology项目地址: https://gitcode.com/gh_mirrors/ka/Kap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
