Cannot set property of undefined：第三方JS库排错

先把话说在前面：这类报错在你接入第三方JS库的时候能把你搞得特别“自我怀疑”。新手通常会陷入一个误区——以为是自己把属性名写错了，反复把单词检查好几遍；有经验的人则知道，这大概率不是手滑，而是“JavaScript里正在设置属性的那个目标对象，根本不具备接收资格”。我最近在帮一个项目接入第三方地图SDK和客服组件时，就连续撞上了 Uncaught TypeError: Cannot set property 'xxx' of undefined，所以今天把这些经验一次讲透。

这个报错，本质上不是“某个属性名不存在”的问题，而是“你要往谁身上塞属性，塞错时机、塞错对象或者塞错方式”的问题。它常见于第三方库入场的各种场景：比如在页面还没把库加载完就去调全局初始化函数，比如自己用同名全局变量把库内部的引用给挤掉了，再比如库更新版本后，它内部默认的数据结构已经被冻结或改成了只读接口，而你还在按老接口去 set。下面我会从报错原理、真实触发场景、排查步骤、修复方案到避坑经验，一次性梳理完。

1. 先看懂这个报错的底层逻辑，再谈怎么解

1.1 报错文案里的几类隐藏信息

很多人只盯着红字里的属性名看，其实真正要关注的是后半段——到底 of 了谁。Chrome 的报错文案往往会带上目标对象的词，比如：

bash复制Uncaught TypeError: Cannot set property 'token' of undefined
Uncaught TypeError: Cannot set property 'token' of null
Uncaught TypeError: Cannot set property 'token' of #<Object> which only has a getter

如果只看中间那一段，忽略 of undefined / of null / which only has a getter，你很容易定位错方向。我一般会先拿 Word 或笔记把整条报错复制下来，拆成三部分看：一是操作类型，是 get 还是 set；二是属性名，到底往哪个字段赋值；三是目标对象当前的状态，它是 undefined、null、不可扩展对象、还是只读访问器。

这里有个容易误导人的点：消息如果写 Cannot set property 'xxx' of undefined，意思是你把 'xxx' 赋值给了 undefined 这个值。换言之，报错行代码大概长这样：someObj.xxx = someValue，而执行到这里时，someObj 是 undefined。但还有一种情况，引擎提示 “Cannot set property 'readOnlyThing' of #<Object>” 时，可能是目标对象存在，但该属性没有 setter，或者该属性被 define 成 writable: false。

把这段拆清楚之后，很多坑你就能靠报错直接猜出来了。第三方库的报错通常不会伪装，它摆明告诉你：你这个赋值动作的对象还没 ready，或者这个对象不支持你这么改。

1.2 赋值操作在 JavaScript 内部到底经历了什么

我们要理解 JS 引擎在执行一句简单赋值 target.prop = value 时，不是拿着属性名去“硬写”。它内部要先做一次 [[Set]] 操作，流程大致是：先确认 target 不是 null 和 undefined，再去当前对象或者它的原型链找有没有同名属性，看属性的描述符（descriptor）是什么类型。

• 如果 target 是 undefined/null，直接抛出 TypeError——“无法给未定义值设置属性”。
• 如果属性是访问器属性（accessor property），并且没有定义 setter，普通模式会悄悄失败，严格模式会直接抛错。
• 如果属性是数据属性（data property），但 writable 是 false，也一样会失败，甚至报 TypeError。
• 如果目标对象被 Object.preventExtensions()、Object.seal() 或 Object.freeze() 封住了，那新增任何属性也都不会成功，严格模式下同样抛错。

为什么这跟第三方 JS 库关系这么大？因为很多第三方库不会只往自己内部闭包里塞状态，它往往会给一个全局对象、DOM 节点实例或你传入的配置对象追加属性。比如地图 SDK 初始化后，为了让你后续能取到实例，会往某些对象上挂一个全局句柄；客服组件为了支持自定义字段，会往页面配置对象里写属性；埋点 SDK 会往 window 上塞一个全局实例。

这也就意味着，set 的“接收方”可能不是你写的对象，而是库替你维护的内部对象。一旦你的代码跟库的执行时序错位，或者你用某种方式覆盖了库内部的引用，库执行到给这个对象赋值时，对象就