wp-calypso Unified Diff Viewer：用 React 渲染 `git diff` / `diff -u` 统一差异视图的组件实现

• 前端
• CMS

本文围绕 wp-calypso 仓库中的DiffViewer组件（位于 client/components/diff-viewer/），完整讲解它的使用方式、Props 契约、输入格式要求，并结合源码逐层剖析其基于 jsdiff 的 patch 解析、文件名启发式展示、行号计算与差异着色渲染的实现原理，同时给出组件在 Jetpack 站点威胁告警中的真实接入案例。读完本文，你将能独立在 React 项目中接入并定制一个可直接展示 unified diff 文本的可视化差异查看器。

组件定位：把文本 diff 变成人眼可读的对比视图

DiffViewer是 wp-calypso 前端组件库中的一个展示型组件，它的唯一职责是：将git diff或diff -u输出的 unified diff（统一差异格式）纯文本，渲染成视觉化的文件对比视图——包括文件名字段、左右行号列、上下文行、删除行与新增行的区分着色，让熟悉 diff 工具的开发者一眼看懂变更内容。

从组件源码 index.jsx 可以看到，组件本身不参与 diff 的生成，只负责"解析 + 渲染"两端：解析依赖 jsdiff（npmdiff包）的parsePatch，渲染则完全基于 React 元素完成。它适合所有"手头已经有一段 patch 文本，需要以结构化、可读形式呈现"的场景，例如代码评审工具、构建日志差异展示、安全告警详情页等。

快速上手：两行代码接入

组件以默认导出形式提供，按仓库规范从calypso/components/diff-viewer引入。README 中的最小用法如下：

import DiffViewer from 'calypso/components/diff-viewer'; export const CommitView = ( { commitHash, description, diff } ) => ( <div> <div> <a href="https://wordpress.com">{ commitHash }</a> </div> <p>{ description }</p> <DiffViewer diff={ diff } /> </div> );

在 wp-calypso 项目中，更常用的引入方式也可以直接写相对路径components/diff-viewer（组件内部示例 docs/example.jsx 即使用import DiffViewer from '../index'）。无论哪种方式，组件都会自动加载其内部样式文件 style.scss，无需手动引入 CSS。

Props 契约：只有一个是必填项

组件对外暴露的属性非常精简，README 中给出的完整 Props 表如下：

其中diff是唯一必填（README 中以*标记）属性，默认值为空字符串。从源码 index.jsx 可以看出，组件函数签名就是( { diff } )，只解构这一个 props。即使传入空字符串，parsePatch( '' )也会安全返回空数组，组件渲染为一个空的.diff-viewer容器，不会报错——这保证了在 diff 数据尚未加载完成时可以先渲染占位。

输入格式：必须是完整、保留换行的 patch 文本

README 明确强调了一个关键使用约束：diff属性应当传入 diff 命令输出的完整文本，并且必须包含换行符。组件内部依赖jsdiff的parsePatch去解析这段文本（详见 index.jsx），解析器按行扫描 patch 元信息（diff --git头、index行、---/+++文件对、@@hunk 头）与具体差异行，因此传入半截文本或丢失换行都会导致解析结果不完整。

README 给出的合法输入示例（一段真实的git diff输出）：

diff --git a/circle.yml b/circle.yml index 51455bdb14..bc0622d001 100644 --- a/circle.yml +++ b/circle.yml @@ -1,6 +1,6 @@ machine: node: - version: 8.9.4 + version: 8.11.0 test: pre: - ? |

这段输入在 docs/example.jsx 中以模板字符串形式作为示例代码展示。注意最后一行没有换行符也可以正常解析（hunk 结束即文件结束），但每个 hunk 内部的行必须以换行分隔。

源码实现剖析：从 patch 文本到对比视图

组件源码虽然只有一百余行，却完整实现了"解析 → 分文件 → 分行号 → 分行渲染"的整条流水线。下面逐层拆解。

1. patch 解析与文件级渲染

组件首先调用parsePatch( diff )将文本解析为结构化数据，然后对返回的每个文件对象做map渲染（index.jsx）。jsdiff 解析出的每个文件对象结构形如：

{ oldFileName: 'a/circle.yml', newFileName: 'b/circle.yml', oldHeader: '51455bdb14..bc0622d001 100644', newHeader: '', hunks: [ { oldStart: 1, oldLines: 6, newStart: 1, newLines: 6, lines: [ ' machine:', ' node:', '- version: 8.9.4', '+ version: 8.11.0', ... ] } ] }

每个文件被渲染为两部分：

• .diff-viewer__filename：展示文件名（由filename( file )启发式计算，见下文）；
• .diff-viewer__file：一行三列布局——左侧行号列、右侧行号列、中间差异内容列。

这种"文件头 + 双行号 + 内容"的结构与 GitHub、Bitbucket 等平台的 diff 视图布局一致。

2. 文件名启发式算法filename()

这是组件中最具巧思的工具函数（index.jsx），其目标是用一行文本同时表达 diff 的左右两侧文件名，核心逻辑分四步：

第一步：剥离a/、b/前缀。git diff等工具为区分"左侧内容"与"右侧内容"，会给同一文件加上a/、b/前缀。函数检测oldFileName以a/开头、newFileName以b/开头时，将二者前缀切掉（index.jsx），例如a/circle.yml与b/circle.yml归一化为circle.yml与circle.yml。

第二步：同一文件只显示一个名字。归一化后若prev === next，说明 diff 比较的是同一个文件（随时间/提交的变更），此时调用decompose把路径拆成"目录部分 + 文件名部分"，只渲染一次：目录用.diff-viewer__path-prefix样式（弱化），文件名用.diff-viewer__path样式（强调）（index.jsx）。

第三步：不同文件显示"旧 → 新"。若两侧路径不同，函数遍历两个字符串，记录最长的共享前缀中最后一个/的位置，然后把共享目录部分弱化为 prefix，各自剩余部分以→箭头连接，直观表达"从哪个文件改到哪个文件"（index.jsx）。

第四步：无共享前缀时兜底。若两个路径完全没有公共字符，则分别用decompose拆分后同样以→展示（index.jsx）。

decompose辅助函数（index.jsx）取路径中最后一个/，返回[ 目录, 文件名 ]二元组；若路径无/（如纯文件名circle.yml），则目录为空字符串。

3. 左右行号列的精确计算

组件为每个文件渲染两列行号（left-numbers与right-numbers），行号并非简单地 1、2、3 递增，而是依据 hunk 的起始行号计算：

// 左侧行号：删除行(以 '-' 开头)不占号，其余行从 hunk.oldStart 开始递增 { line[ 0 ] === '+' ? '\u00a0' : hunk.oldStart + lineOffset++ } // 右侧行号：新增行(以 '+' 开头)不占号，其余行从 hunk.newStart 开始递增 { line[ 0 ] === '-' ? '\u00a0' : hunk.newStart + lineOffset++ }

关键点在于：每个 hunk 内维护一个独立的lineOffset计数器（index.jsx），这样：

• 左侧行号遇到新增行（+）时不递增（该行在旧文件中不存在），显示不间断空格\u00a0保持对齐；
• 右侧行号遇到删除行（-）时不递增（该行在新文件中不存在）；
• 上下文行（）与对应侧的变更行正常计数。

由于每次hunk.lines.map重新开始时都会把lineOffset重置为 0（hunk.oldStart + lineOffset++中的起始基数取自 hunk 头部的oldStart/newStart），因此多 hunk 的行号也能正确衔接。

4. 差异行的语义化渲染

中间内容列对 hunk 内每一行根据首字符分发到三种渲染分支（index.jsx）：

switch ( line[ 0 ] ) { case ' ': return <div key={ key }>{ output }</div>; // 上下文行 case '-': return <del key={ key }>{ output }</del>; // 删除行 case '+': return <ins key={ key }>{ output }</ins>; // 新增行 }

两个细节值得注意：

• 使用语义化标签而非 div + class：删除行渲染为<del>、新增行渲染为<ins>，这两者正是 HTML 中表达"已删除内容/已插入内容"的语义标签，对屏幕阅读器和搜索引擎更友好；
• 空行用不间断空格填充：line.slice( 1 ).replace( /^\s*$/, '\u00a0' )先去掉行首的 diff 标记字符，再把纯空白行替换为\u00a0（index.jsx），避免空行因white-space: pre与flex布局坍缩而丢失高度，保证左右行号与内容行始终逐行对齐。

样式设计：一眼区分增删与上下文

组件样式集中在 style.scss，整体采用 Calypso 的设计令牌（CSS 变量）与等宽字体：

• .diff-viewer__filename：中性背景（--color-neutral-10）+font-weight: 600加粗，作为文件分隔头（style.scss）；
• .diff-viewer__file：display: flex横向三列布局，font-family: $monospace等宽字体保证字符对齐，overflow-x: scroll让超长行可横向滚动而非换行（style.scss）；
• .diff-viewer__line-numbers：右对齐（text-align: right）、弱化色文字（--color-text-subtle）、中性底色，视觉上退居内容之后（style.scss）；
• .diff-viewer__lines：flex-grow: 1占满剩余宽度；删除行使用错误色系（背景--color-error-10、文字--color-error-80）且去除下划线装饰（text-decoration: none），新增行使用成功色系（背景--color-success-10、文字--color-success-80）（style.scss）。

红绿语义与 diff 工具配色一致：红色系代表被删除的内容，绿色系代表新加入的内容，上下文行保持默认无背景。

仓库中的真实应用：Jetpack 站点威胁告警

DiffViewer并非孤立组件，它在 wp-calypso 的 Jetpack 安全模块中有实际接入——站点活动日志的威胁告警详情页（client/my-sites/activity/activity-log/threat-alert.jsx）：

• 第 8 行：import DiffViewer from 'calypso/components/diff-viewer';
• 第 67 行：判断威胁对象是否携带diff字段（threat.hasOwnProperty( 'diff' )）；
• 第 327 行：{ threat.diff && <DiffViewer diff={ threat.diff } /> }，仅在存在 diff 数据时渲染。

这段真实用法印证了组件的设计哲学：组件是纯展示型的，数据是否存在由调用方负责判断。安全告警接口返回的恶意代码补丁（patch 文本）通过diff属性传入，即可在界面上向用户展示被修改文件的具体增删内容。这也解释了为何diff属性默认值为''——调用方可以先渲染空视图，待异步数据到达后再传入完整 patch。

使用注意事项与最佳实践

综合 README 说明与源码行为，接入时有几点建议：

1. 传入完整的 diff 文本：不要截断或手动拼接 patch，parsePatch依赖 hunk 头（@@ -x,y +x,y @@）与---/+++文件头来建立结构，缺一行都可能导致文件或 hunk 解析不完整；
2. 保留换行符：组件按行解析，跨行传输时不要用.trim()或 JSON 序列化破坏末尾换行；
3. 依赖 jsdiff 的解析能力：组件从diff/lib/patch/parse导入parsePatch（index.jsx），该 API 自 jsdiff v4 起提供；wp-calypso 的依赖锁定文件 yarn.lock 中记录了diff包（jsdiff）多个版本（含^4.0.2与^8.0.3），接入时需保证diff包可解析parsePatch；
4. 空数据安全：diff传空字符串不会抛错，适合作为数据加载中的占位渲染；
5. 展示层关注点分离：参考 threat-alert 的用法，调用方负责判断diff是否存在，组件只负责"给文本、出视图"。

小结

DiffViewer是一个职责单一、实现精巧的展示型组件：对外只有一个diff字符串属性，对内则由parsePatch负责结构化解析、filename()启发式负责文件名表达、双行号列与<del>/<ins>语义标签负责差异内容的可视化，配合 Calypso 设计令牌完成增删着色。无论是直接复用该组件展示git diff输出，还是参考其"文本 diff → 结构化视图"的渲染流水线来构建自己的差异查看器，client/components/diff-viewer/ 目录下的 index.jsx、style.scss 与 docs/example.jsx 都是可以直接阅读和复用的完整参考实现。

• 前端
• CMS