页面报错时，让 Codex 帮你画出路由、组件和接口对应表

教程定位

这篇教程解决什么问题

这篇文章解决一个很具体的问题：线上某个页面报错了，你只知道页面 URL、浏览器里看到的接口失败、仓库大概在哪里，但不知道这个页面对应哪个前端路由、哪个组件、哪个接口封装、哪个后端处理函数，也不知道本地应该跑哪条启动命令。

这时不要让 Codex 直接“修一下”。更稳的做法是先让它做一次只读追踪：从 URL 出发，沿着路由、组件、数据请求、接口封装、服务端路由、控制器或处理函数，一层一层建立映射表。Codex 的价值不是替你宣布真相，而是快速给出线索、证据位置和可验证路径。最终是否成立，必须由人用路由文件、接口日志、本地运行结果和浏览器 Network 面板复核。

本文的最终产物是一张“页面到代码到接口”的追踪表。它应该回答五件事：这个 URL 被哪个路由接住，页面主体组件在哪里，页面发了哪些请求，请求在客户端和服务端分别经过哪些文件，本地用什么命令可以复现。

使用场景

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

你接到一个报错：运营同事说“项目任务页打不开”。截图里只有一个前端错误提示，地址栏是 `/org/acme/projects/42/tasks?status=open`。你打开仓库，发现里面有 `apps/web`、`apps/admin`、`packages/api-client`、`services/backend`、`legacy-server`，还有一堆路由、组件、接口封装和网关配置。

如果你直接问 Codex：“帮我修这个 bug”，它很可能跳到某个看起来相关的组件，然后猜测一个空值问题。这个猜测不一定错，但它绕过了真正关键的第一步：这个线上页面到底由哪条链路组成。

更好的提问方式是：“先不要改代码，请帮我从这个 URL 和报错材料出发，建立页面、路由、组件、接口调用、服务端处理的对应关系，并列出每一步证据和待验证点。”

这篇文章特别适合这些情况：

这不是一次完整代码审查，也不是让 AI 直接修复生产故障。它是一份面向定位的地图：先把“可能在哪里”变成“证据显示在哪里”，再把“证据显示”交给人验证。

• 单仓库里有多个前端应用，不确定线上域名指向哪个应用。
• 页面 URL 看起来清楚，但代码里有动态路由、重定向、base path 或国际化前缀。
• 浏览器 Network 里有接口失败，但不知道请求是哪个组件或哪个 hook 发出的。
• 后端有网关、BFF、服务层、controller、handler 多层结构，搜接口路径会出现很多结果。
• 本地项目很久没人跑过，README、脚本和环境变量说明散落在不同目录。

材料准备

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

给 Codex 的材料越具体，映射表越有用。最少准备这些信息：

准备材料时要注意两条边界：

建议你在本地先建一个临时材料块，把输入整理成“URL、现象、Network、仓库结构、日志”五段。这样 Codex 不需要从聊天上下文里猜。

1. 报错页面 URL：最好包含完整路径、query、hash。如果是内部系统，可以脱敏域名和组织名，但不要改掉路径结构。
2. 报错现象：页面提示、控制台错误、截图文字、用户操作步骤。
3. 浏览器 Network 线索：失败接口的 method、path、status、response 摘要、request id。如果有成功接口，也可以一起给。
4. 仓库入口：项目根目录、可能相关的前端目录、后端目录。
5. 路由和启动线索：`package.json` scripts、README、Docker Compose、路由文件名、网关配置名。
6. 日志片段：只给和这次请求相关的几行，去掉 token、cookie、手机号、真实邮箱、内部密钥。

• 不要把生产密钥、用户隐私、完整 cookie、Authorization header 贴给 AI。可以保留 header 名称和脱敏后的 request id。
• 在“建立映射表”阶段，明确要求 Codex 只读仓库，不要改代码、不要安装依赖、不要删除文件。等映射确认后，再进入修复阶段。

实操流程

按这套步骤把工作跑起来

第一步，让 Codex 确认这是哪个应用。

很多仓库不是一个应用，而是一组应用。一个线上 URL 可能对应 `apps/web`，也可能对应 `apps/admin`，甚至前端在 `apps/console`，后端在 `services/api`。让 Codex 先读根目录、`package.json`、工作区配置、README 和部署说明，找出最可能的前端应用和启动命令。

你要让它输出证据，而不是只说“看起来是 Next.js”。有用的证据包括：`apps/web/package.json` 里有 `dev` 脚本，`next.config.js` 里配置了 `basePath: "/console"`，部署说明里提到线上域名对应 `apps/admin`，或者根目录 `turbo.json` 里有 `web#dev` 任务。

第二步，用页面 URL 找路由。

Codex 应该把 URL 拆成稳定部分和动态部分。例如 `/org/acme/projects/42/tasks?status=open` 可能对应：

这里最容易出错的是 base path、locale、rewrite 和权限跳转。比如线上地址是 `/console/org/acme/projects/42/tasks`，代码路由可能没有 `/console`，因为它来自 `basePath`。也可能线上地址先被 Nginx rewrite 到 `/app/org/acme/projects/42/tasks`。所以 Codex 找到候选路由后，要列出“为什么认为它匹配”，并把还没验证的部分标出来。

第三步，找页面主体组件和数据入口。

路由文件常常只是一个壳。真正发请求的代码可能在 `TasksPage`、`ProjectTasksView`、`useProjectTasks`、`TaskTable` 或某个 React Query hook 里。让 Codex 沿着 import 关系往下追踪，但不要无限展开所有子组件。它应该优先找这些信号：

如果页面有多个接口，追踪表要把每个接口分开列，不要混成一句“页面调用任务接口”。一个页面可能同时调用项目详情、任务列表、成员列表、权限配置和埋点接口。报错接口只是一条链路，其他接口是辅助背景。

第四步，把客户端接口封装追到真实请求。

很多项目不会在组件里直接写 URL，而是经过一层或多层封装。例如组件调用 `taskApi.list(projectId, filters)`，这个函数再调用 `request.get("/projects/${projectId}/tasks", { params })`，`request` 又会统一加上 `/api` 前缀、租户 header、认证拦截器和错误处理。

这一步的目标不是读完整个 API client，而是回答：浏览器里看到的 `GET /api/projects/42/tasks?status=open`，在前端代码里最早由哪个业务函数触发，中间经过哪个请求封装，最终拼出了什么 method 和 path。

这里必须要求 Codex 标注不确定性。比如它只能确认 `taskApi.list` 最终调用了 `http.get("/projects/${projectId}/tasks")`，但 `/api` 前缀来自运行时环境变量还是代理配置，还需要人工看 dev server 配置和浏览器实际请求。

第五步，把接口路径追到服务端处理链路。

后端定位不能只搜字符串。`/api/projects/42/tasks` 在代码里可能写成：

让 Codex 同时搜索 method 和路径片段，并注意前缀组合。追踪表里最好拆成“网关或 API route”、“controller/handler”、“service/repository”、“外部依赖或数据库表”。如果只能追到 controller，不能假装已经确认了数据库表。

第六步，补上本地复现命令。

页面入口、接口链路都找到后，还要知道怎么跑。Codex 可以从 `package.json`、README、`.env.example`、Compose 文件和 Makefile 中整理出候选命令，例如：

但这些命令也只是候选。人要验证端口、环境变量、mock 开关、代理配置和登录方式。尤其是全栈项目，本地前端跑起来不代表接口也连对了；接口 200 不代表使用了和线上一样的数据源。

第七步，要求 Codex 输出“证据表”，不是长篇猜测。

推荐的追踪表字段如下：

最后一步，用人工检查把映射表从“线索”变成“已验证”。

你需要本地打开页面，看 URL 是否命中同一个路由；打开浏览器 Network，看 method、path、query 是否和表格一致；在后端日志里按 request id 或路径查一次，看 handler 是否真的收到请求；必要时加临时日志或断点，但不要把临时代码提交。只有这些验证完成后，才能把追踪表当成下一步修复依据。

• Next.js App Router：`app/org/[orgSlug]/projects/[projectId]/tasks/page.tsx`
• Next.js Pages Router：`pages/org/[orgSlug]/projects/[projectId]/tasks.tsx`
• React Router：`path="/org/:orgSlug/projects/:projectId/tasks"`
• Vue Router：`/org/:orgSlug/projects/:projectId/tasks`
• 后端模板路由：`GET /org/:orgSlug/projects/:projectId/tasks`
• `fetch("/api/...")`
• `axios.get(...)`
• `apiClient.projects.tasks.list(...)`
• `useQuery(["tasks", projectId], ...)`
• `loader`、`action`、`getServerSideProps`、`server action`
• GraphQL query 名称，例如 `ProjectTasksQuery`
• `router.get("/projects/:projectId/tasks", handler)`
• `@Get("projects/:projectId/tasks")`
• `GET /api/projects/{projectId}/tasks`
• `app.use("/api", projectsRouter)`
• 网关配置 `path: /api/projects/**`
• OpenAPI 生成代码里的 operationId
• 层级：页面 URL、前端路由、页面组件、数据 hook、客户端 API、请求封装、服务端路由、handler/controller、service、数据源、本地启动。
• 候选位置：文件路径和函数名。
• 证据：匹配到的 path、import、调用语句、日志 request id、脚本名。
• 仍需人工验证：需要本地运行、浏览器确认或日志确认的点。
• 置信度：高、中、低，并说明原因。

pnpm install
pnpm --filter web dev
pnpm --filter api dev
docker compose up postgres redis

输入示例

可以直接参考的输入材料

下面是一段可以直接交给 Codex 的输入样例。它刻意使用了虚构项目和脱敏日志，但保留了真实定位时需要的结构。

如果你已经知道项目是 Next.js、React Router、NestJS、Express、Rails 或 Django，也可以补一句：“请优先按这个框架的路由规则查找，但如果证据不支持，请列出其他候选。”

目标：先不要改代码，只帮我建立页面到代码到接口的追踪表。

报错页面：
https://console.example.test/org/acme/projects/42/tasks?status=open

用户操作：
登录后进入项目详情，点击左侧“任务”，页面加载 2 秒后出现空白和错误提示：
Cannot read properties of undefined (reading 'assignee')

浏览器 Console：
TypeError: Cannot read properties of undefined (reading 'assignee')
    at TaskOwnerCell
    at TaskTable

浏览器 Network：
1. GET /api/projects/42/tasks?status=open
   status: 500
   response: {"error":"Cannot read properties of null (reading 'id')","requestId":"req_demo_7f31"}
2. GET /api/projects/42
   status: 200
3. GET /api/projects/42/members
   status: 200

仓库目录线索：
项目根目录是 /workspace/example-suite
可能相关目录：
- apps/console
- packages/api-client
- services/backend
- packages/ui

我已经看到这些文件可能相关：
- package.json
- pnpm-workspace.yaml
- apps/console/package.json
- apps/console/src/routes.tsx
- packages/api-client/src/index.ts
- services/backend/src/main.ts

日志片段：
[2026-06-18T10:14:03.421Z] requestId=req_demo_7f31 method=GET path=/api/projects/42/tasks status=500 userId=u_demo
[2026-06-18T10:14:03.438Z] requestId=req_demo_7f31 error="Cannot read properties of null (reading 'id')" service=task-service

请只读代码，不要修改文件，不要安装依赖，不要启动服务。输出时请标注证据和待验证点。

提示词

可复制使用的提示词

下面这段提示词可以直接复制给 Codex。使用时把方括号里的内容替换成你的真实材料。

如果 Codex 已经在你的本地仓库里运行，还可以把“请不要启动长期进程”改成“可以运行只读搜索命令，可以读取文件；如需启动本地服务，先列出命令让我确认”。

你是一个只读定位助手。请不要修改代码、不要安装依赖、不要启动长期进程。你的任务是从一个报错页面出发，建立“页面 URL -> 前端路由 -> 页面组件 -> 数据请求 -> 客户端 API 封装 -> 服务端路由/handler -> 本地启动命令”的对应关系。

已知材料：

1. 报错页面 URL：
[粘贴完整 URL，保留 path、query、hash，可脱敏域名]

2. 报错现象：
[粘贴用户操作、页面提示、Console 错误、截图文字]

3. 浏览器 Network：
[粘贴失败接口和关键成功接口，包括 method、path、status、response 摘要、request id。不要粘贴 cookie、token、真实隐私数据]

4. 仓库信息：
[粘贴项目根目录、可能相关目录、你已知的文件名]

5. 日志片段：
[粘贴脱敏后的相关日志，尤其是 request id、method、path、status、handler/service 名称]

请按以下步骤工作：

- 先判断最可能的前端应用和后端服务，说明依据。
- 根据 URL 查找前端路由，注意动态参数、base path、locale、rewrite、权限跳转。
- 沿 import 和调用关系找到页面主体组件、数据 hook、接口调用函数。
- 把浏览器 Network 中的接口路径追到客户端请求封装，说明 path 前缀和 query 是在哪里拼出来的。
- 把接口 method/path 追到服务端 route、controller/handler、service 或 repository。只能追到哪里就写到哪里，不要编造数据库表或函数名。
- 整理本地复现需要的候选启动命令，并说明这些命令来自哪些文件。
- 输出一张 Markdown 表格，列为：层级、候选位置、证据、仍需人工验证、置信度。
- 最后列出 3 到 8 个下一步人工检查点。

重要边界：

- 你输出的是线索和映射，不是最终事实。
- 每个结论必须带文件、函数、配置、日志或 Network 证据。
- 如果有多个候选，请都列出来并说明优先级。
- 如果找不到，请写“未找到”和你搜索过的路径/关键词。
- 不要直接建议修复代码，除非我另行要求进入修复阶段。

输出样例

AI 应该输出到什么程度

下面是使用上面提示词后，Codex 可能给出的输出样例。注意：这是样例，不代表你的项目也长这样。真正使用时，每一行都要回到自己的仓库和日志里验证。

教程正文

页面到接口追踪表

| 层级 | 候选位置 | 证据 | 仍需人工验证 | 置信度 | |---|---|---|---|---| | 线上页面 URL | `/org/acme/projects/42/tasks?status=open` | 用户提供的报错 URL；query 中 `status=open` 和失败接口 query 一致 | 确认线上是否有 `/console` base path 被网关剥离 | 高 | | 前端应用 | `apps/console` | `apps/console/package.json` 中 `name: "@example/console"`；README 提到 console 域名；根目录 workspace 包含该应用 | 确认部署配置是否把 console.example.test 指向该应用 | 中 | | 前端路由 | `apps/console/src/routes.tsx` 中 `path="/org/:orgSlug/projects/:projectId/tasks"` | 路由 path 与 URL 动态段匹配；`element={<ProjectTasksPage />}` 指向页面组件 | 本地打开同一路径，确认没有权限重定向到别的页面 | 高 | | 页面组件 | `apps/console/src/pages/projects/ProjectTasksPage.tsx` | 被 routes.tsx 引用；读取 `projectId` 和 `status`；渲染 `<TaskTable />` | 确认线上 sourcemap 中报错组件是否对应同一文件 | 高 | | 数据 hook | `apps/console/src/features/tasks/useProjectTasks.ts` | `useQuery(["project-tasks", projectId, status], () => taskApi.list(projectId, { status }))` | 确认错误状态下是否仍渲染了旧缓存数据 | 高 | | 客户端 API | `packages/api-client/src/tasks.ts` 中 `listProjectTasks` | 调用 `http.get("/projects/${projectId}/tasks", { params })`；和 Network 的 `/projects/42/tasks?status=open` 匹配 | `/api` 前缀不在此文件，需要继续看 http client 配置 | 高 | | 请求封装 | `packages/api-client/src/http.ts` | `baseURL = env.API_BASE_URL ?? "/api"`；response interceptor 会保留 `requestId` | 本地环境变量是否覆盖为其他后端地址 | 中 | | 服务端入口 | `services/backend/src/main.ts` | `app.use("/api", apiRouter)`；说明 `/api` 前缀来自后端入口 | 确认生产是否还有网关层追加或剥离前缀 | 中 | | 服务端路由 | `services/backend/src/routes/projects.ts` | `router.get("/projects/:projectId/tasks", taskController.list)` 与 method/path 匹配 | 用日志 requestId 确认实际命中的 handler | 高 | | Controller | `services/backend/src/controllers/taskController.ts` 中 `list` | 读取 `req.params.projectId` 和 `req.query.status`；调用 `taskService.listProjectTasks` | 需要确认 500 是否在 controller 内抛出还是 service 抛出 | 中 | | Service | `services/backend/src/services/taskService.ts` 中 `listProjectTasks` | 日志中 `service=task-service`；函数内访问 `task.assignee.id` | 需要用本地数据或日志确认 null assignee 是否触发同一错误 | 中 | | 本地前端启动 | `pnpm --filter @example/console dev` | 来自 `apps/console/package.json` 的 `dev` script | 需要确认端口、登录态和 API 代理 | 中 | | 本地后端启动 | `pnpm --filter @example/backend dev` + `docker compose up postgres redis` | 后端 package script 和根目录 compose 文件 | 需要确认 `.env.example` 是否足够复现接口 | 中 |

教程正文

下一步人工检查点

1. 在本地启动 console，访问 `/org/acme/projects/42/tasks?status=open`，确认命中同一路由。
2. 打开浏览器 Network，确认 `GET /api/projects/42/tasks?status=open` 由 `useProjectTasks` 触发。
3. 用 request id `req_demo_7f31` 查生产日志，确认服务端 handler 是 `taskController.list`。
4. 在本地或测试环境检查返回数据里是否存在 `assignee: null` 的任务。
5. 如果要修复，先补充后端或前端空值处理测试，再进入代码修改阶段。

这个输出合格的地方是：它没有只说“问题在任务组件”；它把 URL、路由、组件、hook、API client、后端 route 和启动命令放在一张表里，并且每一行都有证据和待验证点。

但它仍然不是最终事实。比如“服务端入口”“生产网关”“本地后端启动”这几项都只有中等置信度。人必须用实际运行、日志和配置确认之后，才能把它当作修复依据。

人工验收

人要怎么检查和改到可用

人工检查的重点不是把表格改得更漂亮，而是把“Codex 推断”分成三类：已验证、待验证、已排除。

第一类，已验证。你可以用本地运行或日志确认。比如本地打开页面后，浏览器确实请求了 `/api/projects/42/tasks?status=open`；后端日志确实出现同一个 request id；断点确实停在 `taskController.list`。这些行可以在表格里改成“已验证”。

第二类，待验证。Codex 找到了强相关证据，但你还没有运行确认。比如它从 `baseURL = "/api"` 推断出前端请求前缀，但生产环境可能通过 `API_BASE_URL` 改成了另一个域名。这样的结论不能删，但要保留“待验证”。

第三类，已排除。Codex 可能列出两个候选路由，例如 `apps/web` 和 `apps/console` 都有相似路径。你通过部署配置确认线上只指向 `apps/console`，就应该把 `apps/web` 标为已排除，并写明排除依据。

人工复核时建议按这个顺序走：

还要特别检查 Codex 容易“顺手补全”的部分。比如它看到 `TaskService`，可能推断数据库表是 `tasks`；看到 `ProjectTasksPage`，可能推断路由一定叫 `/projects/:id/tasks`。这些推断只有在代码、日志或数据库 schema 中找到证据，才可以写成事实。

这份追踪表最好不要直接贴进故障复盘当结论。更稳的做法是加一列“验证状态”，把每行标成：

当你进入修复阶段时，也不要让 Codex 基于未验证的行改代码。先让它只针对 `verified` 和必要的 `likely` 行提出修复方案，并明确哪些测试可以证明修复覆盖了这条链路。

1. 验证应用归属：域名、部署配置、入口应用是否一致。
2. 验证路由匹配：URL 动态段、base path、locale、rewrite、权限跳转是否一致。
3. 验证组件链路：路由文件是否真的渲染目标组件，报错堆栈是否能对上组件名。
4. 验证接口触发：浏览器 Network 中的请求是否由表格里的 hook 或 API 函数触发。
5. 验证服务端命中：用 request id、访问日志、临时本地日志或断点确认 handler。
6. 验证本地复现：启动命令是否能跑起来，代理和环境变量是否指向预期后端。
7. 验证数据条件：报错是否依赖某种数据形态，例如空成员、缺失权限、删除中的项目。

verified    已用本地运行、日志或配置确认
likely      证据较强，但还没有运行确认
candidate   只是候选，需要继续排查
excluded    已被部署配置、日志或运行结果排除

失败反例

这些失败反例要提前避开

反例一：只让 Codex 搜页面标题。

错误问法是：“这个任务页在哪里？”然后只给截图，不给 URL、Network 或日志。Codex 可能搜到一个标题相似的组件，但这个组件未必是线上页面。正确做法是用 URL、路由和请求一起定位，页面文案只能作为辅助证据。

反例二：把第一个匹配路由当成事实。

在多应用仓库里，`/projects/:id/tasks` 可能同时出现在用户端、管理端和旧版后台。Codex 如果只列第一个搜索结果，很容易错。正确做法是要求它列出所有候选路由，并用域名、部署配置、package 名、入口文件和本地运行结果排优先级。

反例三：忽略 base path 和 rewrite。

线上 URL 是 `/console/org/acme/projects/42/tasks`，代码里只有 `/org/:orgSlug/projects/:projectId/tasks`。如果不检查 `next.config.js`、Vite dev proxy、Nginx、Vercel rewrite 或网关规则，就可能误判“代码里没有这个页面”。正确做法是把 URL 前缀作为单独一行追踪，确认它来自前端 base path 还是外层代理。

反例四：把客户端 API 函数等同于服务端接口。

组件里调用 `taskApi.list`，不代表服务端就一定有 `TaskApiController.list`。中间可能经过 API client、BFF、网关、OpenAPI 生成层或 mock server。正确做法是把“客户端业务函数”和“服务端 handler”拆成两行，中间用 method/path 连接。

反例五：只看失败的 500 接口，不看同页其他接口。

页面报错可能由失败接口触发，也可能由成功接口返回了前端不兼容的数据触发。比如任务列表接口 200，但成员接口返回空数组，组件仍然读 `assignee.name`。正确做法是把关键成功接口也列入背景，至少确认它们是否参与渲染报错组件。

反例六：让 Codex 根据文件名猜数据库表。

看到 `taskService.ts` 就写“查询 tasks 表”，这是不合格的。真实项目可能查的是 ORM model、视图、搜索索引、外部服务或缓存。正确做法是只追到有证据的位置；如果没有读到 repository 或 SQL，就写“数据源未确认”。

反例七：没有本地启动命令。

有些追踪表看起来很完整，但没有说明本地怎么复现。等到修复时，开发者还要重新翻 README。正确做法是在同一张表里附上候选启动命令、来源文件和待验证环境变量。启动命令不一定一次成功，但至少提供了下一步检查入口。

反例八：把 Codex 的输出直接当复盘结论。

Codex 可以读代码、归纳证据、指出候选链路，但它看不到你没有提供的生产网关、灰度配置、运行时环境变量、真实日志上下文和用户权限状态。正确做法是把输出当“排查草图”，由人用日志、浏览器、本地运行和部署配置逐项盖章。

反例九：在映射阶段顺手改代码。

定位还没完成，就让 Codex 改 `TaskOwnerCell` 加可选链，可能会掩盖真正的后端数据问题。正确做法是先完成链路表，确认错误发生在前端渲染、后端响应、数据污染还是权限分支，再决定修复位置。

主题边界

它和相邻主题的区别

这篇文章不是“让 Codex 读完整个仓库”。仓库总览关注模块、技术栈、目录职责和开发流程，适合新成员上手；本文只关注一个报错页面，从一个 URL 追到它的路由、组件、请求和后端处理链路。

这篇文章也不是“让 Codex 修前端报错”。修复文章会讨论空值保护、错误边界、后端契约、测试补充和回归验证；本文停在修复之前，先确认页面和接口的对应关系，避免在错误位置动刀。

它也不是“生成接口文档”。接口文档面向稳定契约，通常整理 method、path、参数、响应和错误码；本文面向故障定位，重点是某个页面如何触发这些接口、经过哪些封装、在哪里可以验证。

它还不是“整理启动命令”。启动命令只是追踪表的一列。真正的产物是页面到代码到接口的完整映射：页面 URL 如何进入前端路由，组件如何发起请求，请求如何抵达服务端，开发者如何在本地复现和验证。

如果你只需要知道“这个项目怎么跑起来”，应该写启动指南。如果你只需要知道“后端接口有哪些”，应该写 API 清单。如果你需要在一个线上页面出错后快速找到对应的前端和后端位置，这篇文章才是正题。