github-pr-diff-tree如何获取PR diff:mediaType diff技巧全解

原创2026-11-06 10:06:531,963 阅读

github-pr-diff-tree如何获取PR diff:mediaType diff技巧全解

🌲 github-pr-diff-tree 是一个超实用的 GitHub Action,它的核心原理正是利用 mediaType 参数请求 PR diff:调用 Pulls API 时附带 mediaType: { format: 'diff' },即可让服务端直接返回原始 unified diff 文本,再经解析后以目录树形式评论到 PR 中,帮助评审者一眼看清本次改动的完整文件结构。

一、它解决了什么问题?

GitHub 的 PR 评审页面虽然能看代码 diff,但当一次 PR 涉及大量文件时,文件分布在哪些目录这类结构信息很容易被评审者忽略。

github-pr-diff-tree 的作用很简单:每当 PR 创建或更新(opened / synchronize 事件)时,它会自动在 PR 下发表评论,用人类可读的"文件树"展示所有变更文件,并标注每个文件的增删改状态:

  • A:新增文件
  • D:删除文件
  • M +x, -y:修改文件及增删行数
  • R:重命名文件

最终效果如下图所示,一条注释就能看清整个 PR 的改动全貌:

github-pr-diff-tree 生成的 PR diff 目录树评论效果

二、核心技巧:用 mediaType 获取 PR diff

这是整篇文章最值钱的知识点 💡。

GitHub REST API 中 GET /repos/{owner}/{repo}/pulls/{pull_number} 默认返回 JSON。但如果请求时声明接受 diff 媒体类型,服务端就会返回纯文本格式的 unified diff。在 Octokit 中,这个技巧的写法就是在请求参数里加上 mediaType:

const {data: raw} = await octokit.rest.pulls.get({
  ...repo,
  pull_number: number,
  mediaType: {
    format: 'diff'
  }
})

对应源码见 src/main.ts。

💡 小知识:mediaType: { format: 'diff' } 会设置 HTTP 请求头 Accept: application/vnd.github.v3.diff。此时响应不再是 JSON 对象,raw 直接就是 diff 字符串,所以源码里用类型断言把它当作 string 使用。

三、把 diff 文本解析成文件列表

拿到 diff 文本后,src/parse.ts 负责逐行"读懂"它。unified diff 的格式非常规整,解析器只需关注几个关键行:

diff 中的行 含义 解析动作
diff --git a/... b/... 新文件段开始 开启下一个文件记录
--- a/路径 / +++ b/路径 源路径 / 目标路径 出现 /dev/null 则判定为新增或删除
@@ ... @@ hunk 开始 统计后续 +/- 行,得到增删行数
rename from/to 重命名 标记为 renamed
Binary files ... differ 二进制文件 标记 binary 并跳过内容

解析结果被规整为统一的结构,类型定义在 src/types.ts 中:每个文件包含 type(added / deleted / modified / renamed)、from、to、additions、deletions 等字段,为下一步构建树结构做好准备。

四、从文件列表到目录树

src/print.ts 把扁平的文件列表组装成嵌套的目录树,再用 ├──、└──、│ 等制表符递归渲染。每个文件行前面还会带上状态标记,例如:

├── src/
│   ├── parse.ts (M +7, -2)
│   └── print.ts (M +131, -0)
└── README.md (M +18, -98)

这样一来,评审者不用逐个点开文件,就能快速判断:哪些目录被触碰了、改动集中在哪里、哪个文件改动最大。

五、快速上手:一键接入你的仓库

在仓库的 .github/workflows/ 下新建 workflow 文件即可,配置非常简单 ✅:

name: 'PR Diff Tree'

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  dump:
    runs-on: ubuntu-latest
    steps:
      - uses: wadackel/github-pr-diff-tree@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

几个值得注意的设计细节:

  • 评论只有一条:Action 会在评论里嵌入一个 HTML 注释标记(<!-- wadackel/github-pr-diff-tree -->),下次触发时先查找已有评论——找到就更新,找不到才新建,避免 PR 被刷屏(见 src/main.ts)。
  • 输入项:唯一必填项是 token,用于调用 API,定义在 action.yml 中。
  • 运行环境:Action 使用 Node.js 打包产物运行,构建与测试脚本见 package.json。

六、小结

回顾一下 github-pr-diff-tree 的技术链路,其实就是四步:

  1. 🎯 用 mediaType: { format: 'diff' } 让 API 直接返回 PR diff 文本
  2. 📄 按 unified diff 规范逐行解析出文件列表与增删行数
  3. 🌲 将文件列表组装为目录树并渲染输出
  4. 💬 以"更新已有评论"的方式发布到 PR

mediaType 控制响应格式这个技巧本身同样适用于其他 GitHub API 场景(比如请求 patch、html 等格式),学会它,你在处理任何 GitHub 数据时都会多一把利器。想要了解完整的用法与贡献流程,可以参阅 README.md。

登录后查看全文
github-pr-diff-tree