Vue.js 报错：TypeError: Cannot set properties of undefined (setting ‘xxx’)

—— 3 分钟定位 + 修复手册

当你在控制台看到：

TypeError: Cannot set properties of undefined (setting 'xxx')

翻译成人话：你想给 undefined 赋值（或给它里面的属性赋值）。
在 Vue 里 99% 是「对象未初始化 / 异步回填 / 深层链缺失」三选一。按本文「场景 → 原因 → 修复」三步法，3 分钟止血。

---

一、快速定位：看堆栈行号

点击控制台报错 → 跳转到 具体文件 + 行号 → 找到 xxx = ... 或 obj.xxx = ... 的位置。

---

二、5 个高频翻车现场 & 修复

1️⃣ 给空对象深层赋值

<script setup>
const user = ref({});           // 只有空壳
user.value.profile.name = 'Tom'; // ❌ profile 不存在
</script>

修复：初始化完整路径 或 使用 Immer/可选链赋值

user.value = { profile: { name: 'Tom' } };   // 一次性
// 或
user.value.profile = { name: 'Tom' };        // 逐层补

---

2️⃣ 异步回填前操作

<script setup>
const list = ref();            // 初始 undefined
onMounted(async () => {
  list.value = await fetchList(); // 异步回来
});
function addItem() {
  list.value.push(item);        // ❌ 首屏点击时尚未赋值
}
</script>

修复：初始空数组 + 可选链

const list = ref([]);           // ✅ 空数组
function addItem() {
  list.value.push(item);        // 安全
}

---

3️⃣ 选项式 API 未声明嵌套对象

export default {
  data() {
    return {
      form: {}                 // ❌ 没有 form.user
    };
  },
  methods: {
    setUser() {
      this.form.user.name = 'Tom'; // 报错
    }
  }
}

修复：初始化完整结构

data() {
  return {
    form: { user: { name: '' } }   // ✅
  };
}

---

4️⃣ 数组索引越界

const arr = ref([1, 2]);
arr.value[5] = 3;   // ❌ 索引 3、4 不存在 → 稀疏数组或 undefined

修复：使用 push / splice / 展开赋值

arr.value.push(3);                // 在尾部添加
// 或
arr.value = [...arr.value, 3];    // 重新生成数组

---

5️⃣ 作用域链丢失（this 指向）

methods: {
  async load() {
    const res = await api();
    this.list = res;        // ❌ 箭头函数或解构导致 this 丢失
  }
}

修复：使用箭头函数或提前缓存 this

methods: {
  load: async function () {
    const res = await api();
    this.list = res;        // ✅ 正确 this
  }
}

---

三、万能「安全赋值」工具链

场景	工具	示例
深层对象	lodash set	set(obj, 'a.b.c', value)
响应式新增	Vue.set / this.$set	Vue.set(obj, 'newProp', val)
数组响应式	splice / push / 展开	arr.value.push(val)

---

四、一句话总结

「Cannot set properties of undefined」= 对象没初始化或索引越界。
初始化完整结构、用响应式 API、不要给 undefined 赋值，报错瞬间消失。

---

最后问候亲爱的朋友们，并邀请你们阅读我的全新著作

📚 《Vue.js 3企业级项目开发实战（微课视频版》