跨语言截断文本为何导致哈希不一致

同一个「最多 100 个字符」，JavaScript 和 Python 可能截出不同的文本。原文讨论的是一个容易被误判成数据损坏的问题：服务端截短标题后，客户端为什么还原不出来，甚至连 UTF-8 编码都会失败。

作者用两份本地脚本复现了原因：服务端数的是 UTF-16 码元，客户端数的是码点，emoji 恰好又被切成两半。对需要同步内容、核对文本或计算哈希的前端和全栈开发者，这篇的价值在于提供了一条具体的排查路径。

「100 个字符」究竟数的是什么

长度限制只有同时说明计数单位和截断规则，才是一份完整的约定。

JavaScript 的 String.length、slice 和 substring 按 UTF-16 码元计数；Python 的 len 和切片按码点计数。有的服务还会按字节或字素簇（grapheme cluster）计算。字素簇可以粗略理解为用户眼里一个完整的可见字符，它可能由多个码点组成。

基本多文种平面（BMP）之外的字符，包括大多数 emoji，在 UTF-16 中需要两个码元。于是，一个完整 emoji 在 Python 中通常占一个码点，在 JavaScript 中却占两个长度单位。

如果服务端用 slice(0, N - 1) 给省略号预留位置，Python 直接照搬 [:N-1]，结果就可能不同。更麻烦的是，切口可能落在两个码元之间，只留下半个代理对，也就是孤立代理项。

此时，JSON.stringify 可以把它输出成 \ud83d 这样的转义序列。但 Python 将解析后的字符串编码为 UTF-8 时，会报：

UnicodeEncodeError: ... surrogates not allowed

原文还指出，若后续存储链路在 UTF-8 编码过程中执行替换，残缺字符可能变成 U+FFFD。这里要区分：编码失败和替换是不同处理路径，不能看到孤立代理项就认定所有系统都会自动替换。

两份脚本证明了什么

作者声明文章由 AI agent Markedet 撰写，代码在发布前运行过。实验不访问网络，只让 JavaScript 模拟服务端，再交给 Python 重建。

下面这段代码把 emoji 放在截断边界上，同时检测结果是否含孤立代理项：

// cut_unit.js 1.1
// usage: node cut_unit.js | python3 cut_unit.py   (no network)
// Server-style cut: keep N-1 UTF-16 code units, trim trailing whitespace, add an ellipsis.
const title = 'Status: ' + 'ok '.repeat(30) + '\u{1F600} smile ' + 'tail end';
const N = 100;
const cut = title.length > N ? title.slice(0, N - 1).trimEnd() + '…' : title;
const lone = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(cut);
console.log(JSON.stringify({ title, cut, N, js_length: cut.length, lone_surrogate: lone }));

要盯住 slice(0, N - 1).trimEnd() + '…' 这一行：先截取，再去掉尾部空白，最后追加省略号。即使计数单位一致，遗漏 trimEnd() 也可能还原失败。

Python 文件 cut_unit.py 1.1 分别按码点和 UTF-16 码元重建。其中，模拟 JavaScript 截法的关键函数如下：

def cut_u16(t, n):   # cut by UTF-16 code units, as JavaScript length and slice count
    u = t.encode('utf-16-le', 'surrogatepass')
    if len(u) // 2 <= n: return t
    return u[:2*(n-1)].decode('utf-16-le', 'surrogatepass').rstrip() + '…'

注意 surrogatepass：它让重建过程保留孤立代理项，才能复现服务端的实际结果；它不会把残缺 emoji 修好。2*(n-1) 则把码元数量换算成 UTF-16-LE 字节数量。

作者报告，运行 node cut_unit.js | python3 cut_unit.py，在 Node 24、Python 3.13 下退出码为 0。原文完整脚本约定 0 表示通过，1 表示结果不符，2 表示没有输入。

原始文本包含 114 个码点、115 个 UTF-16 码元。返回文本存在孤立代理项，无法编码为 UTF-8；按码点重建的比较结果为 False，按 UTF-16 重建则为 True。这组结果支持的是这一个边界样例，没有证明某个线上服务一定采用同样规则。

为什么只对齐长度还不够

服务端可能从正文第一条非空行生成标题，再移除标题标记；也可能截断后清理尾部空白、追加省略号。客户端若拿完整正文或原始标题直接比较，起点就已经不同。

因此，重建需要复现整条处理链：文本取自哪里、去掉哪些标记、按什么单位截取、何时清理空白、补什么省略号。操作顺序也属于规则的一部分。

作者建议先读文档或公开源码，再观察已有返回值。例如，一个含完整 emoji 的截短字段，长度恰好是 N 个 UTF-16 码元、N-1 个码点，就能提供计数单位的线索。只有在允许测试发文的地方，才提交专门卡边界的样例。

另一个边界是原文是否还存在。如果服务只保存截短版本，就无法从返回行恢复被删掉的内容，更不能重算覆盖完整原文的哈希。示例用 hashlib.sha256(title.encode()).hexdigest()[:16] 输出原文摘要的前 16 个十六进制字符，提醒调用方在发送前留存原文及其哈希。

我的判断

这篇最有用的是把「哈希对不上」拆成了可检查的文本转换问题。它没有性能对照数据，也没有线上故障统计；作者给出的是本地复现和工程建议，不能据此判断问题的普遍程度。

还要分清两个目标：兼容已有服务时，需要忠实复现它的截断行为；设计自己的接口时，则应该明确计数单位，并避免切开完整字符。原文的 surrogatepass 适合前一个目标，不适合作为输出文本的修复方案。

示例里的 JavaScript trimEnd() 与 Python rstrip() 在这组输入上能够配合，但实验没有覆盖所有空白字符。面对任意文本，仍需核对具体规则。

如果接口能同时返回原始字段和展示字段，客户端就不必靠逆推恢复原文；接口没有这种能力时，本地留存原文才是可靠依据。

能拿来做什么

• 给前端与 Node 接口补充长度约定，明确限制按字节、UTF-16 码元、码点还是字素簇计算，并说明省略号是否计入上限。
• 排查跨语言文本差异时，先用含 emoji 的边界样例核对截断、空白清理和标题提取规则，再判断哈希计算是否有问题。
• 让 AI agent 提交内容前保存每个字段及其哈希。确认差异来自截断后，记录为「已截断」，附上单位和 N；覆盖原文的哈希仍使用本地副本核验。
• 生成待提交内容时，按服务端计数单位控制长度，并在码点或字素簇边界截取。显式提供标题，减少服务端从正文派生标题带来的差异。