如何处理 Uncaught (in promise) TypeError 错误

当你调试前端应用时,控制台显示:Uncaught (in promise) TypeError: Cannot read property 'type' of undefined。这条错误消息包含两个不同的问题,开发者经常将它们混为一谈。理解这两个问题对于正确处理 JavaScript Promise 错误至关重要。

本文将解释这个错误的实际含义、出现原因,以及如何在浏览器环境中正确处理未捕获的 Promise 拒绝。

‘Uncaught (in promise) TypeError’ 的实际含义

这条错误消息传达了两个独立的问题:

1. TypeError:发生了运行时错误——通常是访问 undefined 或 null 的属性。
2. Uncaught (in promise):产生此错误的 Promise 没有附加拒绝处理器。

浏览器区分这两者,因为 Promise 拒绝的行为与同步错误不同。当同步 TypeError 发生时,执行会立即停止。当相同的错误发生在 Promise 内部时,拒绝会通过 Promise 链传播。如果没有 .catch() 或 try/catch 处理它,浏览器会将其记录为未处理的 Promise 拒绝。

有关 Promise 行为和错误传播的更深入参考,请参阅 MDN 文档中的 Promises。

前端代码中的常见根本原因

异步函数内部抛出的错误

async 函数内部的任何异常都会自动拒绝返回的 Promise:

async function fetchUserData(userId) {
  const response = await fetch(`/api/users/${userId}`)
  const data = await response.json()
  return data.profile.name // 如果 profile 是 undefined,会产生 TypeError
}

fetchUserData(123) // 浮动 Promise——没有附加处理器

缺少 Await 关键字

忘记 await 会创建一个独立执行的浮动 Promise:

async function processData() {
  fetchUserData(123) // 缺少 await——拒绝未被处理
  console.log('Done')
}

遗忘的 .catch() 处理器

没有终端 .catch() 块的 Promise 链会导致拒绝未被处理:

fetch('/api/data')
  .then(res => res.json())
  .then(data => data.items[0].name) // 没有 .catch()——TypeError 传播

延迟附加处理器和微任务时序

浏览器在当前微任务检查点之后确定拒绝是否被处理。如果到那时拒绝还没有处理器,浏览器可能会触发 unhandledrejection 事件并记录控制台警告。稍后附加处理器仍然可能在开发构建中触发警告:

const promise = Promise.reject(new Error('Failed'))

promise.catch(err => console.log('Handled'))

这种时序细微差别解释了为什么一些正确处理的拒绝在开发期间仍可能显示为未处理。

正确的 Async/Await 错误处理模式

在 Await 周围使用本地 try/catch

最可靠的模式是将 await 表达式包装在 try/catch 中:

async function fetchPokemon(id) {
  try {
    const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${id}`)
    const data = await response.json()
    return {
      name: data.name,
      type: data.types[0]?.type.name,
      type2: data.types[1]?.type.name ?? null
    }
  } catch (error) {
    console.error('Fetch failed:', error.message)
    return null
  }
}

返回附加了处理器的 Promise

调用异步函数时,始终处理返回的 Promise:

// 选项 1:使用 try/catch 的 await
await fetchPokemon(25)

// 选项 2:在调用上使用 .catch()
fetchPokemon(25).catch(handleError)

适当地链接 .catch()

将 .catch() 放在 Promise 链的末尾,以捕获链中的任何拒绝:

Promise.all(urls.map(url => fetch(url).then(r => r.json())))
  .then(results => processResults(results))
  .catch(error => showErrorUI(error))

使用 unhandledrejection 事件进行监控

浏览器提供 unhandledrejection 事件用于全局错误监控——而不是作为主要的错误处理机制:

window.addEventListener('unhandledrejection', event => {
  // 记录到错误监控服务
  errorTracker.capture(event.reason)

  // 可选:阻止默认的控制台错误
  event.preventDefault()
})

配套的 rejectionhandled 事件在先前未处理的拒绝后来收到处理器时触发。这些事件对于遥测和捕获漏过本地处理的错误很有用,但它们不应替代正确的 try/catch 和 .catch() 模式。

结论

“Uncaught (in promise) TypeError” 消息同时表示运行时错误和缺失的错误处理。解决问题的两个方面:使用可选链(?.)和空值合并(??)来防止因未定义属性导致的 TypeError,并将异步操作包装在 try/catch 中或为每个 Promise 链附加 .catch() 处理器。将 unhandledrejection 事件保留用于监控,而不是控制流。这些模式将使你的前端代码更具弹性,并保持控制台整洁。

常见问题

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.