fix-bug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fix React Router Bug

修复React Router Bug

Fix the bug reported in the following GitHub issue: $ARGUMENTS

修复以下GitHub Issue中反馈的Bug：$ARGUMENTS

Branching

分支规范

Bug fixes should start from a clean working tree. If there are changes, prompt me to resolve them before continuing.

Bugs should be fixed from the

main

branch in a new branch using the format

{author}/{semantic-branch-name}

(i.e.,

brophdawg11/fix-navigation

git branch {author}/{semantic-branch-name} main
git checkout {author}/{semantic-branch-name}

Bug修复需基于干净的工作树开始。如果存在未提交的更改，请先提示我处理完毕再继续。

Bug修复需基于

main

分支创建新分支，分支命名格式为

{author}/{semantic-branch-name}

（例如

brophdawg11/fix-navigation

）：

git branch {author}/{semantic-branch-name} main
git checkout {author}/{semantic-branch-name}

Workflow

工作流程

1. Fetch and Understand the Issue

1. 获取并理解Issue内容

Use

gh issue view <number> --repo remix-run/react-router

WebFetch

to read the full issue.

Extract:

Bug description and expected vs actual behavior
React Router version and mode (Declarative / Data / Framework / RSC)
Any code snippets in the issue
Links to reproductions (StackBlitz, CodeSandbox, GitHub repo, etc.)

使用

gh issue view <number> --repo remix-run/react-router

或

WebFetch

读取完整Issue内容。

提取以下信息：

Bug描述及预期行为与实际行为的差异
React Router版本和模式（Declarative / Data / Framework / RSC）
Issue中的所有代码片段
复现链接（StackBlitz、CodeSandbox、GitHub仓库等）

2. Validate the Reproduction

2. 验证复现方案

If there's a StackBlitz/CodeSandbox/online sandbox link:

Use
```
WebFetch
```
to read the sandbox URL and extract the relevant code
Identify the exact sequence of events that triggers the bug

If there's a GitHub repository link:

Use
```
WebFetch
```
to read key files (
```
package.json
```
, relevant source files) from the raw GitHub URL
Identify the route configuration, loaders, actions, or components involved

If no reproduction link exists:

Search the issue comments with

gh issue view <number> --repo remix-run/react-router --comments

Look for code snippets in comments
Ask the user: "No reproduction was provided. Can you share a minimal reproduction or paste the relevant code?"

如果存在StackBlitz/CodeSandbox/在线沙箱链接：

使用
```
WebFetch
```
读取沙箱URL并提取相关代码
确定触发Bug的准确事件序列

如果存在GitHub仓库链接：

使用
```
WebFetch
```
从GitHub原始URL读取关键文件（
```
package.json
```
、相关源文件）
确定涉及的路由配置、loader、action或组件

如果没有复现链接：

使用

gh issue view <number> --repo remix-run/react-router --comments

查看Issue评论

查找评论中的代码片段
询问用户："未提供复现方案。能否分享一个最小复现示例或粘贴相关代码？"

3. Identify the Affected Code

3. 定位受影响的代码

Based on the bug, locate the relevant source files. Consult the key file map:

Area	Files
Core router logic	`packages/react-router/lib/router/router.ts`
React components/hooks	`packages/react-router/lib/components.tsx` , `lib/hooks.tsx`
DOM utilities	`packages/react-router/lib/dom/`
Vite/Framework plugin	`packages/react-router-dev/vite/plugin.ts`
RSC	`packages/react-router/lib/rsc/`

Use

Grep

and

Glob

to trace the relevant code paths.

根据Bug定位相关源文件。可参考核心文件映射表：

领域	文件路径
核心路由逻辑	`packages/react-router/lib/router/router.ts`
React组件/Hook	`packages/react-router/lib/components.tsx` , `lib/hooks.tsx`
DOM工具函数	`packages/react-router/lib/dom/`
Vite/框架插件	`packages/react-router-dev/vite/plugin.ts`
RSC	`packages/react-router/lib/rsc/`

使用

Grep

和

Glob

追踪相关代码路径。

4. Write a Failing Test

4. 编写失败测试用例

Unit test (for router logic, hooks, pure component behavior — no build needed):

Location:
```
packages/react-router/__tests__/
```

Use Jest; run with:

pnpm test packages/react-router/__tests__/<file>

Match the style of nearby test files (describe/it blocks,
```
createStaticHandler
```
,
```
createMemoryRouter
```
,
```
render
```
,
```
screen
```
, etc.)

Integration test (for Vite plugin, SSR, hydration, Framework Mode):

Location:
```
integration/
```

Use Playwright with

createFixture()

→

createAppFixture()

→

PlaywrightFixture

Run with:

pnpm test:integration:run --project chromium integration/<file>

Build first if needed:

pnpm test:integration --project chromium

Write the test to reproduce the bug exactly — it must fail before the fix.

Run it and confirm it fails:

bash

pnpm test packages/react-router/__tests__/<file>  # unit

单元测试（适用于路由逻辑、Hook、纯组件行为——无需构建）：

位置：
```
packages/react-router/__tests__/
```

使用Jest；运行命令：

pnpm test packages/react-router/__tests__/<file>

匹配附近测试文件的风格（describe/it块、
```
createStaticHandler
```
、
```
createMemoryRouter
```
、
```
render
```
、
```
screen
```
等）

集成测试（适用于Vite插件、SSR、hydration、框架模式）：

位置：
```
integration/
```

使用Playwright，配合

createFixture()

→

createAppFixture()

→

PlaywrightFixture

运行命令：

pnpm test:integration:run --project chromium integration/<file>

如需构建请先执行：

pnpm test:integration --project chromium

编写的测试需精准复现Bug——修复前测试必须失败。

运行测试并确认其失败：

bash

pnpm test packages/react-router/__tests__/<file>  # unit

or

pnpm test:integration:run --project chromium integration/<file> # integration

undefined

pnpm test:integration:run --project chromium integration/<file> # integration

undefined

5. Implement the Fix

5. 实现修复

Make the minimal change needed to fix the bug
Do not refactor unrelated code
Confirm the fix addresses the root cause, not just the symptom
Consider all five modes: does this fix break anything in Declarative / Data / Framework / RSC?

Run the failing test again — it must now pass:

bash

pnpm test packages/react-router/__tests__/<file>

Run the broader test suite to check for regressions:

bash

pnpm test packages/react-router/

If the fix touches Framework/Vite code, run integration tests too:

bash

pnpm test:integration:run --project chromium

Confirm linting and typechecking pass:

bash

pnpm lint
pnpm typecheck

仅进行修复所需的最小改动
不要重构不相关的代码
确认修复针对的是根本原因，而非表面症状
请考虑所有五种模式：该修复是否会破坏Declarative / Data / Framework / RSC模式下的任何功能？

重新运行之前失败的测试——此时必须通过：

bash

pnpm test packages/react-router/__tests__/<file>

运行更广泛的测试套件以检查回归问题：

bash

pnpm test packages/react-router/

如果修复涉及框架/Vite代码，还需运行集成测试：

bash

pnpm test:integration:run --project chromium

确认lint检查和类型检查通过：

bash

pnpm lint
pnpm typecheck

6. Create a Change file

6. 创建变更文件

Create a change file at

packages/<package>/.changes/<type>.<unique-meaningful-name>.md

<type>

should be either

patch

minor

major

unstable

to indicate the type of API change being made.

Format:

markdown

fix: <brief description of what was fixed>

在

packages/<package>/.changes/<type>.<unique-meaningful-name>.md

路径下创建变更文件。

<type>

应为

patch

、

minor

、

major

或

unstable

，用于标识所做的API变更类型。

格式：

markdown

fix: <brief description of what was fixed>

7. Report Results

7. 汇报结果

Summarize:

What the bug was and why it happened
What code was changed and why
That the test now passes
Any edge cases or related issues noticed

Ask me to review the changes and iterate based on any feedback.

总结以下内容：

Bug的具体内容及产生原因
修改了哪些代码以及修改原因
测试现已通过
注意到的任何边界情况或相关问题

请我审核更改，并根据反馈进行迭代。

8. Open PR

8. 提交PR

Once I approve the fix, commit the changes and open a PR to

main

. Include a

Closes #NNNN

in the description to link the PR to the original issue. Also link the issue in the

Development

sidebar

一旦我批准修复，提交更改并向

main

分支发起PR。在PR描述中包含

Closes #NNNN

以将PR与原始Issue关联。同时在

Development

侧边栏中关联该Issue。