2025年 GitHub 与 Stack Overflow 中 20 大经典前端 Bug 总结

全栈前端老曹

于 2025-06-09 07:50:41 发布

阅读量903

点赞数 24

分类专栏：前端业务实践文章标签： github 前端 bug javascript vue react stack overflow

本文链接：https://blog.csdn.net/qq_38060125/article/details/148484788

版权

前端业务实践专栏收录该内容

21 篇文章

订阅专栏

🧠 2025年 GitHub 与 Stack Overflow 中 20 大经典前端 Bug 总结

涵盖 Vue、React、JavaScript、TypeScript、CSS 等主流技术栈，附带详细注释与排查时间估算（适合面试 & 实战）

📌 背景说明

在 2024-2025 年的前端开发社区中，GitHub Issues 和 Stack Overflow 上出现了大量关于现代框架（Vue 3、React 18+、Next.js、Svelte）和语言特性（TypeScript、ES Modules、Web Components）的常见 bug。以下是老曹整理的 20 个最经典且高频出现的前端 Bug，并按技术栈分类，每个都包含：

✅ Bug 描述
🔍 报错信息或表现
⚙️ 常见原因
💡 解决方案
🕒 排查时间预估（适用于初学者 / 高级开发者）
🧪 示例代码 + 注释
📌 来源链接（GitHub Issue / Stack Overflow）

🎯 分类目录

类别	内容
🟨 JavaScript 基础类	异步问题、类型错误、内存泄漏等
🟩 TypeScript 类型类	类型推断失败、泛型不匹配、类型守卫未生效
🟥 CSS/样式类	响应式失效、flex 布局异常、z-index 不生效
🟦 Vue 组件类	生命周期问题、响应式更新失败、v-model 同步异常
🟪 React 组件类	useEffect 依赖项遗漏、组件未卸载、ref 使用不当
🟫 构建工具类	Webpack 打包错误、Vite 配置问题、Babel 编译失败
🟰 第三方库类	Axios 请求失败、Element Plus/Vant 兼容性问题
🟱 浏览器兼容类	Safari 移动端样式异常、IE11 Polyfill 缺失

📚 20 个经典前端 Bug 清单（含详细分析）

❗Bug #1：`Uncaught TypeError: Cannot assign to read only property 'exports' of object '#<Object>'`

平台：Webpack + Babel + CommonJS

报错信息：

Uncaught TypeError: Cannot assign to read only property 'exports' of object '#<Object>'

常见场景：
- 在 ES Module 项目中混用 require() 和 module.exports
- 使用了不兼容的第三方模块（如旧版 UMD 模块）
解决方案：
- 使用 import 替代 require()
- 升级第三方库版本
- 修改 Webpack 配置为 experiments.outputModule: true（ESM 输出）
排查时间：
- 初级：1~2 小时
- 高级：15~30 分钟
来源：GitHub Issue

❗Bug #2：`TypeError: Cannot destructure property 'name' of 'undefined' as it is undefined.`

平台：React / Vue

报错信息：

TypeError: Cannot destructure property 'name' of 'undefined' as it is undefined.

常见场景：
- 从接口获取的数据为空，直接解构导致崩溃
- props 默认值未设置，父组件未传参
解决方案：
- 设置默认值：const { name = 'default' } = props;
- 使用可选链：props?.name
- 添加类型检查（PropTypes / TypeScript）
排查时间：
- 初级：30 分钟 ~ 1 小时
- 高级：10 分钟内定位
来源：Stack Overflow

❗Bug #3：`Cannot find module 'vue' or its type declarations.`

平台：VSCode + TypeScript + Vue 3

报错信息：

Cannot find module 'vue' or its type declarations.

常见场景：
- Vue 未安装或未正确引入
- tsconfig.json 未配置路径映射

解决方案：

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vite/client", "vue"]
  }
}

安装 vue 类型：npm install @types/vue --save-dev

排查时间：
- 初级：1~2 小时
- 高级：10 分钟内解决
来源：GitHub Issue

❗Bug #4：`Maximum update depth exceeded. React will block this component from rendering again...`

平台：React

报错信息：

Maximum update depth exceeded. React will block this component from rendering again...

常见场景：
- 在 useEffect 中修改状态，但未设置依赖项
- 循环调用 setState

解决方案：

useEffect(() => {
  setData(fetchData());
}, [dependency]); // 必须添加依赖项

排查时间：
- 初级：1 小时以上
- 高级：15 分钟内定位
来源：Stack Overflow

❗Bug #5：`TypeError: Cannot set properties of undefined (setting 'token')`

平台：Vue / React + Vuex / Redux

报错信息：

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

常见场景：
- Vuex store 未正确挂载
- 使用了未定义的对象属性（如 store.state.auth.token 但 auth 为 undefined）
解决方案：
```
state: {
  auth: null,
}
```
- 初始化对象属性避免空引用
- 使用可选链 state.auth?.token
排查时间：
- 初级：30 分钟 ~ 1 小时
- 高级：10 分钟内定位
来源：GitHub Issue

❗Bug #6：`Component name “XXX” should always be multi-word`

平台：Vue 3 + ESLint

报错信息：

Component name “Header” should always be multi-word

常见场景：
- 单词命名组件违反 Vue 最佳实践

解决方案：

export default defineComponent({
  name: 'MainHeader', // 改为多单词
});

关闭规则（不推荐）：

// .eslintrc.js
rules: {
  'vue/multi-word-component-names': 0
}

排查时间：
- 初级：10 分钟
- 高级：快速识别并修复
来源：GitHub Issue

❗Bug #7：`Property 'value' does not exist on type '{}'`

平台：TypeScript + Vue 3 Composition API

报错信息：

Property 'value' does not exist on type '{}'

常见场景：
- 使用 reactive() 或 ref() 未指定初始值

解决方案：

const form = reactive<{ value?: string }>({});

显式声明类型

排查时间：
- 初级：30 分钟
- 高级：5 分钟内解决
来源：Stack Overflow

❗Bug #8：`Error: A listener indicated an asynchronous response by returning true, but the message channel closed before a response was received`

平台：Chrome 扩展开发

报错信息：

Error: A listener indicated an asynchronous response by returning true, but the message channel closed before a response was received

常见场景：
- Chrome 扩展中异步返回数据未使用 sendResponse

解决方案：

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  setTimeout(() => {
    sendResponse({ data: 'success' });
  }, 1000);
  return true;
});

排查时间：
- 初级：2 小时
- 高级：30 分钟
来源：GitHub Issue

❗Bug #9：`The requested module 'xxx' does not provide an export named 'default'`

平台：Vite + ESM + React / Vue

报错信息：

The requested module 'xxx' does not provide an export named 'default'

常见场景：
- 使用了 CJS 模块却以 ESM 方式导入
- 动态导入路径错误

解决方案：

import MyComponent from './MyComponent.vue'; // ✅ 正确
import { default as MyComponent } from './MyComponent.vue'; // ✅ 可用于 CJS 模块

排查时间：
- 初级：1 小时
- 高级：10 分钟
来源：GitHub Issue

❗Bug #10：`TypeError: Cannot use ‘in’ operator on non-iterable instance`

平台：React / Vue + Babel

报错信息：

TypeError: Cannot use 'in' operator on non-iterable instance

常见场景：
- 对非数组/对象使用展开运算符
- 使用了未初始化的 ref

解决方案：

const arr = ref<number[]>([]);
const list = [...arr.value]; // ✅ 使用 .value

排查时间：
- 初级：30 分钟
- 高级：5 分钟内定位
来源：Stack Overflow

❗Bug #11：`ReferenceError: regeneratorRuntime is not defined`

平台：Webpack + async/await

报错信息：

ReferenceError: regeneratorRuntime is not defined

常见场景：
- 未启用 Babel 的 regenerator-runtime 支持

解决方案：

npm install --save-dev @babel/plugin-transform-runtime

// babel.config.js
plugins: ['@babel/plugin-transform-runtime']

排查时间：
- 初级：1 小时
- 高级：15 分钟
来源：GitHub Issue

❗Bug #12：`Unexpected token 'export'`

平台：Node.js + ES Modules
报错信息：
```
Unexpected token 'export'
```
常见场景：
- 使用 import/export 但在 Node 环境中运行 .js 文件
解决方案：
- 使用 .mjs 后缀
- 设置 "type": "module" in package.json
- 使用 node --experimental-specifier-resolution=node 运行
排查时间：
- 初级：1~2 小时
- 高级：15 分钟
来源：GitHub Issue

❗Bug #13：`TypeError: Cannot read property 'map' of undefined`

平台：React / Vue

报错信息：

TypeError: Cannot read property 'map' of undefined

常见场景：
- 数据未加载完成就执行 map
- 接口返回结构错误

解决方案：

const list = data ? data.items : [];
list.map(...) // ✅ 加保护

排查时间：
- 初级：30 分钟
- 高级：5 分钟
来源：Stack Overflow

❗Bug #14：`TypeError: Failed to fetch dynamically imported module`

平台：Vue 3 + Vite + 动态导入

报错信息：

TypeError: Failed to fetch dynamically imported module

常见场景：
- 动态导入路径错误
- 路由懒加载失败

解决方案：

() => import('../views/Dashboard.vue') // ✅ 路径必须相对正确

排查时间：
- 初级：1 小时
- 高级：15 分钟
来源：GitHub Issue

❗Bug #15：`TypeError: Cannot convert undefined or null to object`

平台：React / Vue + Object.keys / for…in

报错信息：

TypeError: Cannot convert undefined or null to object

常见场景：
- 对 null / undefined 使用 Object.keys

解决方案：

const keys = Object.keys(obj || {}); // ✅ 做空值处理

排查时间：
- 初级：30 分钟
- 高级：5 分钟
来源：Stack Overflow

❗Bug #16：`TypeError: Cannot set property 'innerText' of null`

平台：原生 JS / DOM 操作

报错信息：

TypeError: Cannot set property 'innerText' of null

常见场景：
- DOM 元素未找到
- 组件未渲染完就操作 DOM

解决方案：

const el = document.getElementById('my-el');
if (el) el.innerText = 'Hello';

排查时间：
- 初级：30 分钟
- 高级：5 分钟
来源：GitHub Issue

❗Bug #17：`TypeError: Cannot spread non-iterable instance`

平台：React / Vue + 展开语法

报错信息：

TypeError: Cannot spread non-iterable instance

常见场景：
- 对象不是数组但使用 ...

解决方案：

const arr = Array.isArray(data) ? data : [];

排查时间：
- 初级：30 分钟
- 高级：5 分钟
来源：Stack Overflow

❗Bug #18：`TypeError: Cannot read property 'length' of undefined`

平台：React / Vue + 数组访问

报错信息：

TypeError: Cannot read property 'length' of undefined

常见场景：
- 数据未赋值前就访问 length

解决方案：

const count = items ? items.length : 0;

排查时间：
- 初级：30 分钟
- 高级：5 分钟
来源：GitHub Issue

❗Bug #19：`Uncaught (in promise) TypeError: Failed to execute 'put' on 'Cache': Request failed`

平台：PWA + Service Worker

报错信息：

Failed to execute 'put' on 'Cache': Request failed

常见场景：
- 请求失败后仍尝试缓存

解决方案：

fetch(request).then(response => {
  if (response.ok) cache.put(request, response);
});

排查时间：
- 初级：1 小时
- 高级：15 分钟
来源：GitHub Issue

❗Bug #20：`RangeError: Maximum call stack size exceeded`

平台：React / Vue + 递归组件

报错信息：

RangeError: Maximum call stack size exceeded

常见场景：
- 组件自身嵌套调用
- 无限循环（如 computed 返回自身）

解决方案：

const computedValue = computed(() => {
  return computedValue.value + 1; // ❌ 死循环
});

避免自引用计算

排查时间：
- 初级：1 小时
- 高级：15 分钟
来源：Stack Overflow

📊 Bug 总览表格

序号	报错信息	技术栈	排查难度	时间预估
1	Cannot assign to read only property ‘exports’	Webpack	中	1h
2	Cannot destructure property ‘name’	React/Vue	中	30min
3	Cannot find module ‘vue’	TypeScript	中	1h
4	Maximum update depth exceeded	React	中	1h
5	Cannot set properties of undefined	Vuex/Redux	中	30min
6	Component name should be multi-word	Vue	低	10min
7	Property ‘value’ does not exist on type ‘{}’	TypeScript	中	30min
8	Listener returned true but no response sent	Chrome 扩展	高	1h30min
9	Does not provide an export named ‘default’	Vite	中	30min
10	Cannot use ‘in’ operator on non-iterable	React/Vue	中	30min
11	RegeneratorRuntime is not defined	Babel	中	1h
12	Unexpected token ‘export’	Node.js	中	1h
13	Failed to read ‘length’ of undefined	React/Vue	中	30min
14	Failed to fetch dynamically imported module	Vue/Vue Router	中	30min
15	Cannot set property ‘innerText’ of null	原生 JS	低	5min
16	Cannot spread non-iterable instance	React/Vue	中	30min
17	Failed to execute ‘put’ on ‘Cache’	PWA	中	1h
18	Maximum call stack size exceeded	React/Vue	高	1h
19	Cannot use ‘in’ operator on non-iterable	React/Vue	中	30min
20	Failed to load resource: net::ERR_BLOCKED_BY_CLIENT	浏览器插件拦截	低	5min

🛠️ 排查建议总结表

场景	排查技巧
控制台报错	查看完整堆栈，定位源头
网络请求失败	查看 Network 面板，检查 status code
样式异常	使用 Elements 面板审查 DOM 和 CSS
跨域问题	检查 Access-Control-Allow-Origin
异步错误	使用 try/catch / .catch()
类型错误	使用 TypeScript 提前捕获
构建失败	查看 webpack/vite 构建日志
内存泄漏	使用 Performance 面板 Memory Profiler
状态管理	使用 Devtools 查看 store 更新路径
第三方库问题	查看 issue / 文档 / 版本是否兼容

📦 推荐调试工具清单

工具	用途
Chrome DevTools	主流调试工具
Vue Devtools	Vue 组件状态跟踪
React Devtools	React 组件树、props、state
Lighthouse	页面性能评分
Fiddler / Charles	网络请求抓包
Sentry	线上错误收集
ESLint / Prettier	语法规范检查
Jest / Cypress	自动化测试
Git Bisect	定位哪个 commit 引入 bug

📚 推荐学习资源

类型	推荐资料
Vue	《Vue 3 设计与实现》
React	《React Hooks 详解》
TypeScript	《TypeScript 深度解析》
构建工具	《Webpack 从入门到进阶》
线上监控	《前端监控实战》
开发规范	Airbnb Style Guide
项目架构	《大型前端架构设计》