前端页面一启动就红屏：让 Codex 先抓第一条有效错误

教程定位

这篇教程解决什么问题

前端红屏最让人烦的地方，不是它报错了，而是它一次性把很多东西都扔到你脸上：浏览器页面上有一大段红色堆栈，终端里同时刷出编译警告、框架提示、热更新信息，控制台还夹着旧的网络失败、React Strict Mode 的重复调用、source map 找不到、某个第三方 SDK 初始化失败。你明明只想知道“到底哪一行把页面打崩了”，却很容易被一整屏噪音带着走。

这篇教程讲一个非常具体的用法：页面本地启动后直接红屏时，不要让 Codex 一上来“修复所有错误”，而是让它先从第一条有效错误开始定位。所谓第一条有效错误，不一定是屏幕上视觉最醒目的那一条，也不一定是日志最后一条。它通常是最早导致渲染中断、编译失败或模块加载失败的错误，能解释后续一串连锁报错。比如 `Cannot read properties of undefined` 可能让组件渲染中断，后面的路由加载失败、边界组件报错、热更新断开，都只是跟着倒下。

本文的目标读者是前端应用维护者。你可能不是这个页面的最初作者，只是今天轮到你值守。你拉起本地项目，页面直接变成红屏，堆栈里既有 `react-dom`、`vite`、`next`、`webpack`、`router` 这类框架代码，也有几个业务组件路径。你手上有浏览器错误截图、终端日志、最近改动记录，以及大概相关的组件路径。你要的不是一个“前端调试百科”，而是一份能落地的根因判断和最小修复建议：先确认是哪条错误最早、最有效；再判断它和最近改动是否有关；最后给出最小改动点和验证办法。

这套做法的价值在于把红屏处理从“看到什么修什么”变成“先建立证据顺序”。Codex 很适合读堆栈、对照文件路径、归纳最近改动，但你必须明确约束它：不要被框架噪音带偏，不要把所有红字都当根因，不要为了消除日志而大面积重构。红屏初步定位最重要的产物不是代码，而是一张判断卡：第一条有效错误是什么、它为什么可能是根因、哪些日志只是噪音、需要怎样复现、最小修复建议是什么、哪些地方本轮不要碰。

本文用一个虚构但真实感很强的场景来讲：一个 React + Vite 后台项目，本地启动后进入订单详情页直接红屏。页面提示 `Cannot read properties of undefined (reading 'name')`，堆栈里混着 `react-dom`、路由懒加载、错误边界和业务组件 `OrderCustomerPanel.tsx`。终端同时提示 source map、CSS 变量和一个无关的 API 404。最近改动里有人把 `customer` 字段改成了可选，并调整了订单详情接口返回结构。我们会让 Codex 先识别第一条有效错误，再给出最小修复建议，而不是直接搜索所有 `customer.name` 并批量加问号。

使用场景

什么情况下最适合用这一套

你是一个前端应用维护者。早上接到同事消息：“本地订单详情页打开就是红屏，你帮忙看一下？”你切到项目目录，启动开发服务器，登录后台，点击订单详情，页面红屏。屏幕上有一段很长的错误：

终端里也不安静：

如果你只靠肉眼，很容易同时追三条线：是不是 Vite 的 source map 坏了？是不是 `customer-tags` 这个接口 404 导致页面挂了？是不是列表 key 警告导致渲染异常？是不是路由错误边界有问题？这就是红屏定位的典型陷阱：日志越多，越容易把“后果”当成“原因”。

这时候让 Codex 介入是有价值的，但提示词要写对。你不应该只说“帮我修复这个红屏”。这句话太宽，Codex 可能会打开一堆文件，尝试加空值判断、改接口调用、处理 source map、顺手修 key 警告，最后改动变得很散。更稳的做法是先让它做一件事：按时间和因果关系整理错误，找出第一条有效错误。

第一条有效错误通常满足几个特征。它在浏览器错误栈里位置靠前，能直接指向业务代码；它出现后，页面渲染中断；它能解释后续噪音为什么发生；它和最近改动存在合理关联。比如上面的 `OrderCustomerPanel.tsx:42` 读取 `customer.name`，而最近改动刚好把订单详情里的 `customer` 改成可选字段，这就是很强的线索。相比之下，source map 失败一般不会让业务页面红屏；列表 key 警告通常是警告，不是导致页面崩溃的异常；`customer-tags?customerId=undefined` 可能是连锁后果，因为组件已经拿不到 `customer.id`。

你要让 Codex 做的不是“消灭所有红字”，而是把红字分层：

这种分层能帮你把工作量压到最小。比如最终修复可能只是：订单详情页在 `customer` 缺失时显示“客户信息暂不可用”，并且不要发起依赖 `customer.id` 的标签请求；或者把接口适配层补齐默认结构。无论哪种，修复都应该围绕根因，而不是围绕所有日志逐条开工。

1. 根因候选：最早导致渲染失败或模块失败的错误。
2. 强相关线索：最近改动、业务路径、接口结构变化、触发页面。
3. 连锁后果：错误边界捕获、路由渲染失败、后续请求参数变成 undefined。
4. 环境噪音：source map、热更新提示、开发模式重复日志、无关 warning。
5. 需要人工确认：接口数据是否符合预期、空状态在产品上应该怎么展示。

TypeError: Cannot read properties of undefined (reading 'name')
    at OrderCustomerPanel (src/features/orders/detail/OrderCustomerPanel.tsx:42:28)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:16305:18)
    at mountIndeterminateComponent (...)
    at beginWork (...)
    at HTMLUnknownElement.callCallback (...)

[vite] Internal server error: Failed to load source map
GET /api/orders/ORDER_DEMO_001 200
GET /api/customer-tags?customerId=undefined 404
Warning: Each child in a list should have a unique "key" prop.
React Router caught the following error during render TypeError...

材料准备

开始前先把材料和边界备齐

开始前，准备四类材料。材料越具体，Codex 越能从第一条有效错误开始，而不是在日志海里漂。

第一类是浏览器红屏截图或截图文字。截图最好包含错误类型、第一段业务堆栈、文件路径和行号。如果你不能直接上传图，就把关键内容转成文字。不要只写“页面红屏”，要写清楚：页面路径是什么，错误类型是什么，第一条业务代码路径是什么，红屏发生在进入页面时、点击按钮时，还是热更新后。

第二类是终端日志。终端日志不要从启动开始全部粘贴几千行，先截取红屏前后最相关的一段。尤其要保留时间顺序：页面请求、编译结果、第一条 error、随后出现的 warning 或重复 error。如果日志里有真实 token、手机号、订单号、客户名，要先脱敏。可以保留结构，例如 `ORDER_DEMO_001`、`user_demo`、`customer_id: null`。

第三类是最近改动。红屏定位时，“最近改了什么”常常比“日志里有多少红字”更关键。你可以给 Codex 一份简短清单：最近合并的分支、刚改过的组件、接口字段变化、依赖升级、路由配置调整、环境变量变动。不要把最近改动写成“很多地方都动了”，而要尽量具体到路径和意图：`src/features/orders/detail/normalizeOrder.ts` 调整了订单接口适配；`OrderCustomerPanel.tsx` 新增客户标签展示；`orderApi.ts` 把 `customer` 标记为可选。

第四类是相关组件路径。你不需要一开始就让 Codex 全仓库搜索。先给它红屏堆栈里出现的业务文件、最近改动的文件、页面入口文件、接口适配文件。这样它能按证据顺序读文件。对于红屏初步定位，优先级通常是：堆栈第一条业务代码、该组件的 props 来源、数据适配层、最近改动 diff、相邻测试。

准备材料时，还要把目标写窄。建议明确告诉 Codex：

这几句看起来像限制，其实是在帮 Codex建立正确的调试顺序。红屏场景最怕同时处理十个信号，最后每个都处理一点，但没有一个能解释页面为什么崩。你要让它像值班维护者一样先问：“哪条错误最早打断了页面？它为什么会发生？我怎样用最小步骤复现和验证？”

• 先不要写代码。
• 先找第一条有效错误。
• 区分根因、连锁后果和噪音日志。
• 结合最近改动判断最可能的触发点。
• 给出最小修复建议，不要做大范围重构。
• 如果需要继续读文件，请按优先级列出来。
• 不要把 warning、source map、热更新日志直接当根因。

实操流程

按这套步骤把工作跑起来

第一步，把红屏现象写成可复现句子。不要只说“本地启动后页面报错”，而要写成：“运行开发服务器后，登录运营后台，打开 `/orders/ORDER_DEMO_001`，页面在详情主体渲染阶段红屏；刷新后仍然复现；返回订单列表不红屏。”这句话能帮助 Codex 判断错误范围是页面级、路由级、数据级，还是全局启动级。如果整个应用首页都打不开，方向可能是依赖、入口、环境变量或编译错误；如果只有订单详情红屏，方向就更偏业务组件和接口数据。

第二步，让 Codex 按时间顺序整理日志。红屏日志常常重复出现，尤其 React 开发模式下可能重复渲染，错误边界也会再报一次。你要它不要按“出现次数最多”排序，而要按“最早出现并能解释后续错误”的顺序排序。比如第一条是 `Cannot read properties of undefined (reading 'name')`，后面是 `React Router caught the following error during render`，那么后者大概率是框架捕获前者后的包装信息，不是新的根因。

第三步，找出第一条业务堆栈。堆栈里会有大量框架函数：`renderWithHooks`、`beginWork`、`performUnitOfWork`、`commitRoot`、`RouterProvider`、`ErrorBoundary`。这些路径说明错误发生在渲染流程中，但通常不该优先修改。你要让 Codex 从上往下找第一个项目源码路径，例如 `src/features/orders/detail/OrderCustomerPanel.tsx:42`。这类路径才是初步定位的入口。

第四步，判断错误类型。不同错误类型对应不同的定位方式。`Cannot read properties of undefined` 多半是数据为空或结构变化；`Module not found` 多半是路径、导出或依赖问题；`Element type is invalid` 常见于默认导出和命名导出混用；`Hydration failed` 要关注服务端和客户端渲染差异；`Maximum update depth exceeded` 要看 effect 依赖和状态更新循环。让 Codex 先给错误分类，再读文件，效率会高很多。

第五步，把错误和最近改动对上。让 Codex 明确回答：“这条错误是否能被最近改动解释？”例如最近把 `OrderDetail.customer` 从必填改成可选，而红屏行刚好读取 `order.customer.name`，这就是强相关。如果最近改的是主题色 CSS，而红屏是数据空值，那相关性就弱。相关性判断不能靠猜，要靠字段、路径、调用链和复现条件。

第六步，区分噪音日志。噪音不是完全没用，而是不应该排在根因前面。source map 加载失败可能影响调试体验，但很少导致业务渲染红屏；React key warning 需要修，但通常不会打断页面；热更新断开可能是红屏后的结果；接口 404 要看它发生在红屏前还是后，以及它是否直接抛异常。让 Codex 给每条噪音写“不作为首要根因的理由”，能防止它被红字牵着走。

第七步，要求最小修复建议。最小修复建议不是“加一堆可选链”这么粗糙，而是要说明修在什么层。可能有三种选择：在数据适配层补默认结构，在组件层处理空状态，在请求层阻止 undefined 参数继续发起。哪一种最小，要看业务语义。如果 `customer` 缺失是合法状态，组件应该显示空状态；如果接口合同要求一定有 `customer`，则应该在适配层或类型上暴露异常；如果只有标签请求依赖 `customer.id`，则需要加请求条件。Codex 应该把选择理由写出来。

第八步，建立验证步骤。红屏修复后不能只看页面不红了。至少要验证：同一路径刷新不红屏；有客户信息的订单正常显示姓名和标签；无客户信息的订单显示合理空状态；不会再发起 `customerId=undefined` 的请求；订单列表不受影响；终端没有新增编译错误。若有现成测试，可以补一个最小测试；若没有，也要写清手工验证步骤。

第九步，再进入代码修改。只有当根因判断、最小修复点和验证计划都清楚之后，才让 Codex 修改代码。第二轮提示词要强调：“只改最小修复点；不要处理已归类为噪音的日志；如果发现根因判断不成立，先停下来重新说明。”这样可以避免它在实施阶段又被其他红字带偏。

第十步，交付时把“未处理日志”说清楚。红屏修复后，控制台可能还剩一些 warning。不要为了交付漂亮而把它们都混进这次修复。你可以写：“本次修复根因是 `customer` 为空导致详情页渲染崩溃；source map warning 和列表 key warning 已确认不是本次红屏根因，未在本次处理。”这会让评审者知道你不是漏看，而是有意控范围。

输入示例

可以直接参考的输入材料

下面是一份可以直接交给 Codex 的材料包。它模拟一个 React + Vite 后台应用的红屏定位场景，真实项目中请替换成自己的路径和日志，并先脱敏业务数据。

这份输入把“错误发生在哪里”“后续还有哪些红字”“最近改了什么”放在了一起。Codex 拿到后，就不应该直接被 `customer-tags 404` 或 source map warning 带走，而应该先解释 `OrderCustomerPanel.tsx:42` 为什么是更强的根因候选。

场景：
本地启动后，订单列表可以打开，但点击进入订单详情页会红屏。刷新订单详情页仍然红屏。

复现步骤：
1. 运行 pnpm dev。
2. 登录运营后台。
3. 打开 /orders。
4. 点击订单 ORDER_DEMO_001。
5. 进入 /orders/ORDER_DEMO_001 后页面直接红屏。

浏览器红屏第一段：
TypeError: Cannot read properties of undefined (reading 'name')
    at OrderCustomerPanel (src/features/orders/detail/OrderCustomerPanel.tsx:42:28)
    at OrderDetailPage (src/features/orders/detail/OrderDetailPage.tsx:118:9)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:16305:18)
    at mountIndeterminateComponent (node_modules/react-dom/cjs/react-dom.development.js:20074:13)
    at beginWork (node_modules/react-dom/cjs/react-dom.development.js:21587:16)

浏览器控制台后续日志：
- React Router caught the following error during render TypeError: Cannot read properties of undefined (reading 'name')
- GET http://localhost:5173/api/customer-tags?customerId=undefined 404
- Warning: Each child in a list should have a unique "key" prop.
- [vite] hot updated: /src/features/orders/detail/OrderDetailPage.tsx

终端日志片段：
- GET /api/orders/ORDER_DEMO_001 200
- response body 中 customer 为 null
- Failed to load source map for /node_modules/some-sdk/index.js.map
- GET /api/customer-tags?customerId=undefined 404

最近改动：
- src/features/orders/detail/normalizeOrder.ts：把接口返回的 customer 字段从必填改为可选。
- src/features/orders/detail/OrderCustomerPanel.tsx：新增客户标签区域。
- src/features/orders/api/orderApi.ts：OrderDetail 类型里 customer?: Customer | null。
- 未改动路由配置，未升级 React/Vite。

相关路径：
- src/features/orders/detail/OrderCustomerPanel.tsx
- src/features/orders/detail/OrderDetailPage.tsx
- src/features/orders/detail/normalizeOrder.ts
- src/features/orders/api/orderApi.ts

本轮目标：
请先不要写代码。请从第一条有效错误开始定位，区分根因堆栈、噪音日志和可复现步骤，输出根因判断和最小修复建议。

提示词

可复制使用的提示词

下面这段提示词可以直接复制。适合页面红屏、堆栈混乱、你还不确定该改哪里的场景。

如果你已经确认要进入修复阶段，可以继续用第二段提示词：

第一段用于定位，第二段用于实施。把这两步分开，会比一句“帮我修红屏”稳得多。

你现在只做前端红屏的初步定位，不要写代码。

我会给你浏览器红屏、终端日志、最近改动和相关组件路径。请你从“第一条有效错误”开始分析，不要把所有红字都当根因。

材料如下：
[粘贴浏览器错误截图文字或第一段堆栈]
[粘贴终端日志片段]
[粘贴最近改动]
[粘贴相关组件路径]
[粘贴可复现步骤]

请输出：
1. 可复现条件：用一句话说明在什么页面、什么操作、什么数据状态下红屏。
2. 第一条有效错误：指出最早能解释红屏的错误、文件路径、行号和错误类型。
3. 根因候选：说明为什么这条错误比后续日志更可能是根因。
4. 噪音日志分组：把框架包装、热更新、source map、warning、连锁请求失败分别标出，并说明为什么它们暂不作为首要根因。
5. 最近改动关联：判断最近改动中哪一项最可能触发该错误，证据是什么。
6. 需要继续读取的文件：按优先级列出，不要一次性扩大到全仓库。
7. 最小修复建议：只给建议，不写代码。说明修在组件层、数据适配层还是请求层，以及为什么。
8. 验证计划：包括当前红屏、相邻正常数据、空数据、后续请求、回归测试或手工检查。
9. 不处理清单：列出本轮不建议处理的日志或文件，避免修复范围扩大。

约束：
- 不要直接建议“全局加可选链”。
- 不要把 source map、热更新日志、框架捕获信息直接当根因。
- 如果证据不足，请说需要补充什么，不要猜。
- 最终产物是根因判断和最小修复建议，不是完整重构方案。

现在进入最小修复阶段。

请只围绕上一轮确认的第一条有效错误和最小修复点修改代码。不要处理已经归类为噪音的日志，不要顺手修 warning，不要重构相邻组件。

如果你在读代码后发现上一轮根因判断不成立，请先停止，重新输出：
- 新的第一条有效错误
- 原判断为什么不成立
- 是否需要扩大读取范围

如果判断成立，请输出：
- 将修改的文件
- 修改理由
- 最小验证方式
确认后再改。

输出样例

AI 应该输出到什么程度

下面是一份较理想的 AI 输出样例。它的重点是先建立错误顺序和证据关系，而不是急着改代码。

这份输出有几个好处。它没有被最长的框架堆栈吓住，也没有被最后一条 404 带偏；它把 `customer` 缺失、组件读取、后续请求失败串成了一个因果链；它还保留了一个重要分支：如果业务确认 `customer` 不该为空，修复点就应该从组件层上移到数据适配层。红屏定位需要这种“有主判断，也保留条件”的表达。

1. 可复现条件
运行本地开发服务器后，进入订单详情页 /orders/ORDER_DEMO_001，在详情页主体渲染阶段红屏。订单列表可打开，说明问题更可能集中在订单详情页面或详情数据处理链路，而不是全局启动失败。

2. 第一条有效错误
第一条有效错误是：
TypeError: Cannot read properties of undefined (reading 'name')
at OrderCustomerPanel (src/features/orders/detail/OrderCustomerPanel.tsx:42:28)

理由：
- 它是浏览器红屏堆栈中最早出现的业务源码路径。
- 错误类型是渲染阶段读取 undefined 属性，足以直接导致 React 组件渲染失败。
- 后续 React Router error 是路由错误边界捕获该异常后的包装信息。
- 终端显示订单接口 200，但 customer 为 null，能解释为什么读取 name 会失败。

3. 根因候选
最可能根因是：OrderCustomerPanel 假设 order.customer 一定存在，但最近接口类型已经允许 customer 为 null 或 undefined。组件在渲染时直接读取 customer.name，导致详情页红屏。

4. 噪音日志分组
- React Router caught error：框架捕获信息，是第一条 TypeError 的后续包装。
- customer-tags?customerId=undefined 404：可能是同一个 customer 缺失造成的连锁请求失败，需要在修复时一并确认是否应阻止请求，但不是最早红屏原因。
- unique key warning：需要后续单独处理，但它通常不会导致当前红屏。
- source map 加载失败：影响调试体验，不直接解释订单详情组件读取 undefined。
- hot updated：开发服务器热更新提示，不是根因。

5. 最近改动关联
强相关改动：
- normalizeOrder.ts 将 customer 改为可选。
- orderApi.ts 类型声明为 customer?: Customer | null。
- OrderCustomerPanel.tsx 新增客户标签区域。

这三项和当前错误能形成完整链路：接口允许 customer 为空，详情组件仍按必填读取，标签请求继续使用 customerId，导致红屏和后续 404。

6. 需要继续读取的文件
优先级如下：
1. src/features/orders/detail/OrderCustomerPanel.tsx：确认第 42 行读取方式，以及是否有标签请求。
2. src/features/orders/detail/OrderDetailPage.tsx：确认传入 OrderCustomerPanel 的 props。
3. src/features/orders/detail/normalizeOrder.ts：确认 customer 为空是合法保留，还是适配层漏了默认值。
4. src/features/orders/api/orderApi.ts：确认类型合同。

7. 最小修复建议
优先建议在 OrderCustomerPanel 组件层处理 customer 缺失，因为当前材料显示接口 200 且 customer 为 null 可能是合法数据状态。组件应在 customer 缺失时展示“客户信息暂不可用”或相应空状态，并避免发起依赖 customer.id 的标签请求。

如果产品或接口合同确认订单详情必须有 customer，则更合适的修复点可能是 normalizeOrder.ts，在适配层统一补齐或抛出可控错误。当前证据下，不建议全仓库批量给 customer.name 加可选链。

8. 验证计划
- 打开 /orders/ORDER_DEMO_001，页面不再红屏。
- customer 为 null 时，客户区域显示空状态。
- customer 存在时，姓名和客户标签正常显示。
- 不再请求 /api/customer-tags?customerId=undefined。
- 订单列表页面不受影响。
- 若有组件测试，补充 customer 为 null 的渲染测试。

9. 不处理清单
- 不处理 source map warning：不是本次红屏根因。
- 不处理 unique key warning：属于相邻质量问题，避免扩大范围。
- 不修改路由错误边界：它只是捕获了业务组件异常。
- 不全局替换 customer.name：容易掩盖数据合同问题，并扩大影响面。

人工验收

人要怎么检查和改到可用

Codex 的初步定位不能直接替代人工判断。它能帮你整理证据，但最终要由维护者确认业务语义和修复边界。尤其是前端红屏，很多错误看起来都是技术问题，背后其实是数据合同或产品状态没有说清楚。

第一项人工检查是复现条件。你要亲自确认红屏是否稳定复现，是否只发生在某一个页面、某一类数据、某个角色或某个环境。如果只有本地复现，测试环境不复现，可能还涉及 mock 数据、代理配置或本地缓存。如果刷新后消失，可能是热更新或状态残留。如果只有特定订单红屏，就要看该订单数据是否缺字段。复现条件不稳，Codex 的根因判断也会变虚。

第二项人工检查是第一条有效错误是否真的最早。浏览器控制台有时会折叠旧日志，终端日志也可能乱序。你可以清空控制台、重新启动开发服务器、重新走复现步骤，再记录第一条 error。必要时打开浏览器 Network 面板确认接口返回时间和数据结构。不要拿一个已经滚动很久的控制台直接判断根因。

第三项人工检查是业务数据合同。比如 `customer` 为空到底是合法状态，还是后端数据异常？如果是合法状态，前端组件应该展示空状态；如果不合法，前端可能要给出可控错误提示，同时推动接口修复；如果是迁移期间的临时状态，可能需要兼容一段时间。Codex 可以提出选项，但不能替产品、后端和前端负责人拍板。

第四项人工检查是最小修复层级。很多红屏都可以用可选链短平快压住，比如把 `customer.name` 改成 `customer?.name`。但这不总是好修复。可选链可能让页面不崩，却留下空白区域、错误请求或错误业务判断。你要检查它是否同时处理了展示、交互和副作用。比如组件不红了，但仍然请求 `customer-tags?customerId=undefined`，这就不是完整的最小修复。

第五项人工检查是相邻状态。红屏修复不能只验证坏数据。还要看正常数据是否被破坏：有客户的订单是否仍显示姓名，客户标签是否正常加载，未付款订单和已取消订单是否仍走原逻辑。很多“修空值”的改动会不小心把正常路径也改成空状态。

第六项人工检查是修复范围。红屏往往诱人扩大范围，因为你会在日志里看到很多看起来也该处理的问题。建议把本次修复限制在能解释红屏的最小链路上。source map、key warning、旧接口 404、无关样式警告，可以记录到后续任务，但不要混进当前修复，除非它们被证明就是根因。

第七项人工检查是测试或手工验证记录。即使没有自动化测试，也要留下清楚的验证步骤：用什么账号、打开什么路径、使用什么订单状态、预期看到什么、不应出现什么请求。这样后续评审和回归时，不会只剩一句“本地看过了”。

最后，修改 Codex 给出的建议时，要把“为什么不按它的建议做”写出来。比如 Codex 建议在组件层显示空状态，但你确认 `customer` 按接口合同必须存在，于是改在 `normalizeOrder.ts` 做显式异常和兜底。这不是推翻 AI，而是把业务判断补上。好的红屏定位，是 AI 整理证据，人来确认语义，然后再做最小改动。

失败反例

这些失败反例要提前避开

反例 1：看到最后一条日志就开修。

很多人会盯着控制台最后一条红色日志，例如 `GET /api/customer-tags?customerId=undefined 404`，然后直接去修接口请求。请求参数确实不对，但它可能是 `customer` 缺失后的连锁后果。如果你只给请求加一个默认 id，红屏行 `customer.name` 仍然会崩。正确做法是先问：这条 404 出现在红屏前还是后？它是否能解释页面为什么渲染中断？有没有更早的业务堆栈指向组件读取 undefined？

反例 2：把框架堆栈当成要修改的地方。

红屏堆栈里经常出现大量 `react-dom`、`RouterProvider`、`ErrorBoundary`、`vite`、`webpack`。新手看到 `React Router caught the following error`，可能会怀疑路由配置或错误边界坏了。实际上，路由只是捕获了下层组件抛出的异常。你让 Codex 修改错误边界，最多是把红屏样式换掉，根因仍然存在。正确做法是从堆栈里找第一条项目源码路径，再沿着 props 和数据来源向上查。

反例 3：全局搜索后批量加可选链。

`Cannot read properties of undefined (reading 'name')` 很容易诱发一个危险动作：搜索所有 `.name` 或 `customer.name`，然后批量改成 `customer?.name`。这会让 diff 看起来很勤快，也可能压住一部分报错，但它没有回答关键问题：哪个数据结构变了？哪些地方应该允许为空？哪些地方为空反而是异常？批量可选链会掩盖数据合同问题，还可能把正常页面变成静默空白。正确做法是先定位红屏页面的第一条有效错误，再决定是在组件层、适配层还是请求层修。

反例 4：把 warning 和 error 混成一个任务。

控制台里如果同时有 key warning、deprecated warning、source map warning 和 TypeError，有些人会让 Codex “一起处理一下”。这会把一个可控的小修复变成一串无关改动。warning 值得处理，但它们不一定导致红屏。当前任务应该优先恢复页面可用，并保留最小验证面。其他质量问题可以登记为后续任务。

反例 5：没有复现步骤，只贴一张截图。

只贴截图给 Codex，可能得到一个看似合理但证据不足的判断。截图显示的是结果，不一定显示触发路径。页面是首次进入红屏，还是点击某个 tab 后红屏？是特定订单，还是所有订单？是本地 mock，还是连接测试环境？没有复现步骤，Codex 很容易把根因推得过宽。正确做法是至少给出页面路径、操作步骤、数据状态和刷新结果。

反例 6：最小修复建议不包含验证。

有些 AI 输出会停在“建议加空值判断”。这还不够。红屏修复必须带验证计划，尤其要覆盖相邻状态。比如 `customer` 为空不红了，但 `customer` 存在时标签不加载了；或者详情页好了，列表页因为共享组件改动出现空白。没有验证计划的“最小修复”，很容易只是“最小改动”，不是“最小可靠修复”。

主题边界

它和相邻主题的区别

这篇文章只讨论前端红屏的初步定位，重点是让 Codex 从第一条有效错误开始，区分根因堆栈、噪音日志、最近改动和可复现步骤。它不追求一次性修完所有前端质量问题，也不讨论完整的异常监控体系。

它和“小 bug 控范围”的区别在于：小 bug 控范围通常已经知道现象和大概位置，重点是防止改多；红屏定位则还处在“哪条错误才是根因”的阶段，重点是先排日志顺序和因果关系。前者的核心产物是不改清单，后者的核心产物是第一条有效错误和最小修复建议。

它和“读取新仓库第一小时”的区别在于：新仓库阅读关注项目结构、入口、依赖、运行方式和业务边界；红屏定位关注一次具体故障。你不需要在红屏时理解全仓库，只需要围绕复现路径、堆栈业务路径和最近改动读到足够证据。

它和“扩展接口响应要小心”的区别在于：接口响应文章更关注字段合同、兼容性和上下游影响；红屏定位可能会碰到接口字段变化，但它的第一目标是解释页面为什么崩。只有当第一条有效错误指向数据结构变化时，才需要进入接口合同讨论。

它和“让 Codex 保护别人改动”的区别在于：共享工作区文章强调协作边界，避免误改他人文件；本文强调调试边界，避免误把噪音日志当根因。两者可以一起用。比如多人同时修红屏时，你既要让 Codex 只动负责文件，也要让它只围绕第一条有效错误分析。

它和完整修复 PR 指南也不同。本文交付物是根因判断和最小修复建议，不一定直接包含代码修改。对于线上或准生产故障，这个中间产物很重要：先把判断说清楚，再决定谁来改、改哪一层、是否需要后端确认、是否需要补测试。红屏越吓人，越要先稳住顺序。第一条有效错误，就是这个顺序的起点。