JS给只读属性赋值报错TypeError怎么解决

作者:函数茶馆时间:2026-11-18 19:18:06浏览:87

详细解析JavaScript中向只读属性赋值抛出TypeError的原因,通过属性描述符排查、对象状态检测,提供不可变复制更新、重设writable属性、补全setter访问器以及调用原生替代API等实用解决方案。

JavaScript 故障排查 环境:ECMAScript 5+ / 严格模式 (Strict Mode) 更新状态:经最新标准语法检验
JS给只读属性赋值报错TypeError怎么解决
图 1:只读属性赋值报错的触发原因与核心解决路径概览
核心回答与解决路径:在 JavaScript 严格模式下,向只读属性赋值会抛出 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。

JS给只读属性赋值报错TypeError怎么解决
图 2:JavaScript 内部属性描述符校验与 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 = '李四';
框架场景提示: 在 React 中直接修改 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 个步骤进行精准诊断:

JS给只读属性赋值报错TypeError怎么解决
图 3:系统化排查定位只读属性根源的 4 步工作流
  1. 第一步:从错误调用栈提取对象与属性名
    查看报错信息中的行号,明确是在对哪一个变量的哪一个字段进行赋值。例如提示 Cannot assign to read only property 'score' of object '#<Object>',说明变量持有的对象中,属性名为 score。
  2. 第二步:调用 Object.getOwnPropertyDescriptor 打印描述符
    在赋值代码前插入诊断代码,打印目标属性的内部配置元数据:
    console.log(Object.getOwnPropertyDescriptor(targetObj, 'score'));
    • 如果打印结果中 writable: false,说明属于数据只读;
    • 如果存在 get 函数但 set: undefined,说明缺少赋值入口;
    • 如果返回 undefined,说明该属性并非对象自身属性,而是继承自原型链(需使用 Object.getPrototypeOf 继续排查)。
  3. 第三步:使用 Object.isFrozen 检测对象状态
    执行 console.log(Object.isFrozen(targetObj))。如果返回 true,说明整个对象已经被深冻结或浅冻结,对象本身的任何属性均不允许被原地修改。
  4. 第四步:确认对象所有权归属
    判断该对象是自己编写创建的本地配置对象,还是来自外部依赖、组件 Props 或框架 Store。外部对象必须遵循不可变数据规范,禁止就地修改。

四、4种实用解决方案与完整代码实现

JS给只读属性赋值报错TypeError怎么解决
图 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,更能指导我们在工程中建立良好的状态管理规范:

JS给只读属性赋值报错TypeError怎么解决
图 5:处理只读属性赋值报错的全流程防错闭环与工程防范

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" 或模块环境下执行,避免因为非严格模式的静默失败而误以为修复成功;
  • 引用独立性:如果采用了复制新对象的方式,确认业务后续逻辑使用的是新对象引用,原对象没有继续在其他组件中被错误依赖;
  • 单元测试覆盖:为相关赋值操作补充单元测试,验证在合法输入与异常输入下均能按预期产生状态更新。
作者最新文章
相关文章
更多