2025年最值得用的GitHub发布工具：action-gh-release 新手入门教程
项目地址: https://gitcode.com/GitHub_Trending/ac/action-gh-release 你还在手动创建GitHub Releases吗？每次发版都要重复上传文件、编写说明、设置标签？现在，这些繁琐工作可以交给 action-gh-release 自动完成！本文将带你5分钟上手这款2025年最热门的GitHub发布工具，从安装到高级配置全程实操，让你的项目发布效率提升10倍。
读完本文你将学会：
- 3步实现自动化发布流程
- 批量上传发布资产（二进制文件、文档等）
- 自定义发布说明和权限控制
- 解决常见的发布失败问题
什么是 action-gh-release？
action-gh-release 是一款GitHub Action（GitHub动作）工具，能在Linux、Windows和macOS环境中自动创建GitHub Releases。它像一个"发布助手"，可以帮你自动完成打标签、上传文件、生成说明等重复工作。项目核心代码位于 src/main.ts，支持多种自定义配置，适用于各种规模的开源项目。
快速开始：3步实现自动发布
第1步：准备工作
确保你的项目满足：
- 已创建GitHub仓库
- 使用Git进行版本控制
- 了解基本的GitHub Actions语法
第2步：创建工作流文件
在项目根目录创建 .github/workflows/release.yml 文件，复制以下代码：
name: 自动发布
on:
push:
tags:
- "v*.*.*" # 匹配 v1.0.0 这样的标签
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: 拉取代码
uses: actions/checkout@v5
- name: 创建发布
uses: softprops/action-gh-release@v2
with:
files: |
LICENSE
README.md
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
第3步：测试发布流程
-
提交代码并创建标签：
git tag -a v1.0.0 -m "第一个正式版本" git push origin v1.0.0 -
打开GitHub仓库的Actions页面，查看"自动发布"工作流运行状态
-
完成后访问Releases页面，即可看到自动创建的发布
核心功能详解
上传发布资产
想要上传编译后的二进制文件或安装包？只需修改 files 参数：
- name: 创建发布
uses: softprops/action-gh-release@v2
with:
files: |
dist/*.zip
LICENSE
README.md
支持通配符 * 和多行列表，完整语法可查看 action.yml 中的文件参数说明。
自动生成发布说明
不想手动写更新日志？可以：
-
使用外部文件作为发布说明：
with: body_path: CHANGELOG.md # 使用[CHANGELOG.md](https://link.gitcode.com/i/4aca5988cdc2c87b99ce6c974adf8a2d)作为说明 -
或启用自动生成功能：
with: generate_release_notes: true # 自动从PR和提交记录生成说明
控制发布权限
根据GitHub安全最佳实践，需要正确设置权限。在工作流中添加：
permissions:
contents: write # 发布需要写入权限
# 如果需要创建讨论，添加：
# discussions: write
完整权限说明见 README.md 权限章节。
高级配置指南
发布到其他仓库
需要跨仓库发布？指定目标仓库和访问令牌：
with:
repository: 组织名/目标仓库名
token: ${{ secrets.CUSTOM_GITHUB_TOKEN }} # 具有目标仓库权限的令牌
创建预发布版本
开发测试阶段可创建预发布版本：
with:
prerelease: true # 标记为预发布
name: "测试版 v1.0.0-beta" # 自定义名称
处理大型文件
对于超过100MB的文件，建议先使用Git LFS跟踪，再通过action-gh-release上传。项目测试目录 tests/data/ 中提供了大文件处理示例。
常见问题解决
文件上传失败
- 检查文件路径是否正确，Windows系统需使用
/而非\ - 设置
fail_on_unmatched_files: true来调试路径问题 - 确认文件大小未超过GitHub的2GB限制
权限错误
- 检查
permissions配置是否包含contents: write - 对于私有仓库，可能需要使用个人访问令牌(PAT)
发布重复创建
- 确保只在标签推送时触发工作流（使用
on: push: tags配置） - 设置
overwrite_files: false避免重复上传
总结与后续学习
通过本文，你已经掌握了action-gh-release的基本用法和高级技巧。这款工具的核心优势在于：
- 跨平台支持（Linux/Windows/macOS）
- 高度可定制的发布流程
- 与GitHub生态无缝集成
想要深入学习，可以查看：
- 官方文档：README.md
- 配置参考：action.yml
- 源码实现：src/github.ts（GitHub API交互部分）
下次发布新版本时，不妨试试本文介绍的自动化流程，让发布工作像喝水一样简单！如果觉得有用，别忘了点赞收藏，关注作者获取更多GitHub效率工具教程。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
