String.prototype.isWellFormed 是 ES2024 新增方法,用于检测字符串是否含孤立代理项;返回 true 表示 UTF-16 良构,false 表示存在非法代理对,常配合 toWellFormed 修复为 U+FFFD。

String.prototype.isWellFormed 是 ECMAScript 2024(ES15)新增的原生方法,用于判断字符串是否为“良构的 Unicode 字符串”,即不含孤立代理项(unpaired surrogates)——也就是常说的“非法代理对”。
什么是非法代理对?
Unicode 中,U+10000 及以上的字符(如 emoji、古文字、部分表情符号)在 UTF-16 编码下需用两个 16 位代码单元表示:一个高位代理(0xD800–0xDBFF)加一个低位代理(0xDC00–0xDFFF)。若只有其中之一(如 "\uD83D" 或 "\uDC00"),就构成非法代理对,会导致字符串解析异常、正则失败、JSON 序列化出错等。
用 isWellFormed 检测非法代理
该方法返回布尔值,true 表示字符串完全由合法 UTF-16 序列组成,无孤立代理;false 表示至少含一个非法代理项。
-
"hello".isWellFormed()→true -
"\uD83D\uDE00".isWellFormed()→true(?,合法代理对) -
"\uD83D".isWellFormed()→false(缺低位代理) -
"abc\uD83Dxyz".isWellFormed()→false(中间插入孤立高位代理)
检测后如何安全处理?
检测出 false 后,常见处理方式包括修复、替换或丢弃非法部分。推荐使用 String.prototype.toWellFormed()(同属 ES2024)自动替换非法代理为 U+FFFD():
-
"\uD83D".toWellFormed()→"" -
"Hi \uD83D xyz".toWellFormed()→"Hi xyz" - 若需保留原始字节意图(如调试),可用
Array.from(str).map(ch => ch.codePointAt(0))手动遍历并识别代理项位置,再做定制处理
兼容性与降级建议
目前(2024 年中)Chrome 123+、Edge 123+、Firefox 125+、Safari 17.4+ 已支持;Node.js 22.0.0+ 原生支持。旧环境可按需添加轻量 polyfill:
- 检查是否定义:
if (!String.prototype.isWellFormed) { ... } - 简易检测逻辑:遍历字符串,对每个
charCodeAt(i)判断是否为代理项,并验证相邻配对关系(注意边界和偏移) - 不建议在生产中自行实现
toWellFormed,因其需精确模拟引擎的 Unicode 处理规则

















