JS给只读属性赋值报错TypeError怎么解决
详细解析JavaScript中向只读属性赋值抛出TypeError的原因,通过属性描述符排查、对象状态检测,提供不可变复制更新、重设writable属性、补全setter访问器以及调用原生替代API等实用解决方案。
TypeError: Cannot assign to read only property 'xxx' of object 异常。导致该报错的本质原因是目标属性的描述符中 writable 属性为 false、对象已被 Object.freeze() 冻结,或者该属性仅定义了 getter 存取器而缺失 setter。解决该问题主要有两种路径:如果目标是外部受保护或框架状态对象(如 React Props、Redux 状态),应使用解构赋值或结构化克隆生成新副本并在副本上赋值;如果目标是开发者完全可控的自有对象,可修改 Object.defineProperty 开启 writable: true,或为属性补齐对应的 set 访问器。
一、报错表现与底层触发机制
在 JavaScript 中给某个对象的属性赋值是一项基本操作。通常情况下,如果对象不存在该属性,解释器会自动创建;如果存在,则直接覆盖原值。然而,当属性处于“只读”保护状态时,赋值行为将受到拦截。
在不同的运行环境下,赋值失败的表现截然不同:
- 严格模式(Strict Mode):执行语句如
"use strict";、ES 模块(import/export)或者 ES6 类(Class)内部。给只读属性赋值会直接抛出TypeError: Cannot assign to read only property '...' of object '#<Object>',中断后续代码运行。 - 非严格模式(Sloppy Mode):赋值操作会被引擎静默忽略,虽然不报错,但属性值丝毫不会改变,赋值表达式依然返回所赋的值。这种静默失败极难察觉,往往会导致后续逻辑出现隐蔽的难以排查的数据异常。
现代前端开发(使用 Vite、Webpack、TypeScript 或现代 Node.js)构建的代码默认全部运行在严格模式下,因此任何对只读属性的赋值尝试都会直接触发 TypeError。
二、产生只读属性的常见场景分析
只读属性并不是凭空出现的,它通常由 JavaScript 原生语法特性或第三方框架的状态保护机制所产生。在解决问题前,首先需要认清目标属性是通过哪种途径变成只读的:
1. 使用 Object.defineProperty 配置了 writable: false
开发者或第三方类库通过属性描述符精确控制对象属性的行为。如果将 writable 显式指定为 false,或者在定义属性时省略了 writable(默认值为 false),该属性即变为只读属性:
"use strict";
const config = {};
Object.defineProperty(config, 'version', {
value: '1.0.0',
writable: false, // 显式设为只读
configurable: true
});
// 触发报错:TypeError: Cannot assign to read only property 'version'
config.version = '2.0.0';
2. 对象被 Object.freeze() 完全冻结
Object.freeze() 会浅层冻结一个对象,使得现有属性不可写(writable: false)、不可重新配置(configurable: false),且不可添加新属性:
"use strict";
const userProfile = Object.freeze({
name: '张三',
role: 'admin'
});
// 触发报错:TypeError: Cannot assign to read only property 'name'
userProfile.name = '李四';
props(例如 props.count = 1)、在 Redux Toolkit 或 Immer 中不按规范在外部修改只读状态快照、或在 Vue 3 中向 readonly() 包装的响应式对象直接赋值,都会触发相同的只读属性错误。
3. 仅定义了 Getter 存取器而未提供 Setter
在类或字面量对象中,如果通过 get propertyName() 定义了计算属性,但没有配套编写 set propertyName(),该属性在运行时同样表现为只读:
"use strict";
class UserSession {
constructor(token) {
this._token = token;
}
get token() {
return this._token;
}
// 未定义 set token(val)
}
const session = new UserSession('abc-123');
// 触发报错:TypeError: Cannot assign to read only property 'token'
session.token = 'xyz-789';
4. 原生只读对象或只读 DOM 属性
浏览器和 JavaScript 原生内置了大量只读属性。例如 Math.PI、全局 undefined,或者 DOM 元素上的只读度量属性(如 element.clientWidth、element.scrollHeight)。试图直接对其赋值同样会触发此错误:
"use strict";
// 试图直接修改只读的 DOM 几何属性
document.body.clientWidth = 1200; // 报错:只读属性不可分配
三、4步快速排查定位只读根源
当控制台爆出 TypeError 时,盲目修改赋值语句往往无法根治问题。建议按照以下 4 个步骤进行精准诊断:
-
第一步:从错误调用栈提取对象与属性名
查看报错信息中的行号,明确是在对哪一个变量的哪一个字段进行赋值。例如提示Cannot assign to read only property 'score' of object '#<Object>',说明变量持有的对象中,属性名为score。 -
第二步:调用 Object.getOwnPropertyDescriptor 打印描述符
在赋值代码前插入诊断代码,打印目标属性的内部配置元数据:console.log(Object.getOwnPropertyDescriptor(targetObj, 'score'));- 如果打印结果中
writable: false,说明属于数据只读; - 如果存在
get函数但set: undefined,说明缺少赋值入口; - 如果返回
undefined,说明该属性并非对象自身属性,而是继承自原型链(需使用Object.getPrototypeOf继续排查)。
- 如果打印结果中
-
第三步:使用 Object.isFrozen 检测对象状态
执行console.log(Object.isFrozen(targetObj))。如果返回true,说明整个对象已经被深冻结或浅冻结,对象本身的任何属性均不允许被原地修改。 -
第四步:确认对象所有权归属
判断该对象是自己编写创建的本地配置对象,还是来自外部依赖、组件 Props 或框架 Store。外部对象必须遵循不可变数据规范,禁止就地修改。
四、4种实用解决方案与完整代码实现
解决方式 1:采用不可变方式(复制对象后更新副本)—— 推荐方案
如果报错的对象来自 React Props、Redux 状态、Vue 3 只读引用,或者被 Object.freeze() 保护,绝对不要试图破坏对象的只读保护。正确的做法是创建该对象的浅拷贝或深拷贝,在全新副本上应用修改:
做法 A:使用 ES6 展开运算符(浅拷贝)
"use strict";
const frozenConfig = Object.freeze({
apiEndpoint: 'https://api.example.com',
timeout: 3000
});
// 错误做法:直接修改只读属性
// frozenConfig.timeout = 5000; // TypeError
// 正确做法:生成新副本并更新
const newConfig = {
...frozenConfig,
timeout: 5000
};
console.log(newConfig.timeout); // 输出: 5000,成功更新且不产生副作用
做法 B:使用 structuredClone 进行深拷贝(针对嵌套对象)
"use strict";
const state = Object.freeze({
user: { profile: { theme: 'light' } }
});
// 对于深层只读结构,使用原生深拷贝
const editableState = structuredClone(state);
editableState.user.profile.theme = 'dark'; // 正常赋值,完全不受冻结限制
解决方式 2:修改属性描述符,开放 writable 权限
如果该对象完全由你的业务逻辑模块创建与维护,只是在定义时误将其设为了只读,可以通过 Object.defineProperty 调整属性描述符,将 writable 重新指定为 true:
"use strict";
const systemSettings = {};
// 原始定义时误设为不可写,但保证 configurable 为 true
Object.defineProperty(systemSettings, 'maxConnections', {
value: 100,
writable: false,
configurable: true // 允许后续重新配置
});
// 修复:重新配置描述符,开放写入权限
Object.defineProperty(systemSettings, 'maxConnections', {
writable: true
});
// 现在可以正常赋值
systemSettings.maxConnections = 250;
console.log(systemSettings.maxConnections); // 输出: 250
configurable 为 true 时,才能重新定义它的描述符。如果原本设置了 configurable: false,调用 Object.defineProperty 同样会抛出 TypeError: Cannot redefine property。
解决方式 3:为访问器属性补齐对应的 Setter 函数
如果报错的属性是一个只定义了 Getter 的计算属性,应该检查设计意图:如果该属性确实需要支持写入操作,必须为其提供对应的 set 方法:
"use strict";
class UserProfile {
constructor(firstName, lastName) {
this._firstName = firstName;
this._lastName = lastName;
}
// 读取器
get fullName() {
return `${this._firstName} ${this._lastName}`;
}
// 补充设置器(Setter),解决只读报错
set fullName(val) {
const parts = val.split(' ');
this._firstName = parts[0] || '';
this._lastName = parts[1] || '';
}
}
const user = new UserProfile('San', 'Zhang');
// 赋值执行,触发 set fullName(),不再抛出异常
user.fullName = 'Si Li';
console.log(user.fullName); // 输出: Si Li
解决方式 4:针对 DOM 或原生只读属性使用正规 API
对于浏览器底层只读的接口(如 DOM 计算尺寸、历史记录或 URL),不能直接对其只读字段赋值,应当改用对应的方法或样式属性进行控制:
| 错误操作(尝试赋值只读属性) | 产生原因 | 正确解决方式 |
|---|---|---|
element.clientWidth = 500; |
clientWidth 为布局测量计算属性,只读 |
使用样式接口:element.style.width = '500px'; |
window.location = 'https://...'; (误用属性) |
某些旧运行环境中将整体赋值或内部属性当作普通对象 | 使用官方导航方法:window.location.assign('https://...'); 或设置 location.href |
document.forms.length = 0; |
HTMLCollection 集合长度只读 |
操作 DOM 节点增删:node.remove() |
五、全流程总结与防御性编程实践
理解只读属性报错的处理不仅能解决眼前的 Bug,更能指导我们在工程中建立良好的状态管理规范:
1. 使用 Reflect.set 增强代码鲁棒性
在编写通用的数据同步、反序列化或动态代理工具函数时,如果无法事先确定目标对象的属性是否可写,可以使用 Reflect.set() 替代直接赋值。Reflect.set() 会返回一个布尔值代表是否写入成功,而不会直接让程序崩溃:
"use strict";
function safeSetProperty(target, prop, value) {
const success = Reflect.set(target, prop, value);
if (!success) {
console.warn(`[防御警告] 属性 ${prop} 处于只读状态,已拦截赋值,建议检查数据流。`);
}
return success;
}
2. 借助 TypeScript 在编译阶段捕获风险
在大型工程中,推荐使用 TypeScript 的 readonly 关键字标记不应被变动的属性。这样在开发阶段,IDE 和编译器就能在敲下代码的第一时间标红,无需等到运行时触发 TypeError:
interface AppConfig {
readonly apiKey: string;
readonly maxRetries: number;
}
const config: AppConfig = { apiKey: 'secret-123', maxRetries: 3 };
// TS 编译期即报错:Cannot assign to 'apiKey' because it is a read-only property.
// config.apiKey = 'new-key';
3. 修复后的验证自查清单
- 严格模式确认:确保自测代码位于
"use strict"或模块环境下执行,避免因为非严格模式的静默失败而误以为修复成功; - 引用独立性:如果采用了复制新对象的方式,确认业务后续逻辑使用的是新对象引用,原对象没有继续在其他组件中被错误依赖;
- 单元测试覆盖:为相关赋值操作补充单元测试,验证在合法输入与异常输入下均能按预期产生状态更新。
JS使用[...str]展开运算符遍历含Emoji的字符串
2026-11-18 19:20:39
JS数组遍历方法对比:for、forEach与for...of的区别及选择
2026-11-18 19:12:55
怎么用JS递归遍历并修改深层嵌套JSON对象
2026-11-18 17:38:06
JavaScript怎么定义和初始化Map对象
2026-11-18 14:53:57
JS字符串中怎么使用\n表示换行
2026-11-18 13:55:12






![为什么JS对象直接转字符串显示[object Object]](https://img.javascript.cn/tit/articles/13236/20261106/84aa86eb15b66540a3d64b4a7a62b181d4058395daf4aec8f716e9fa4f562f53.webp)

