---
id: file-routes
track: learn
product: router
locale: zh-CN
order: 3
revision: 2
sourceCheckedOn: "2026-08-03"
versionRange: "Router ^1"
verifiedAgainst: "@tanstack/react-router@1.170.18 + @tanstack/router-cli@1.167.21"
contentModel: 2
prerequisites:
  - "已启动 Start 项目"
sourceRefs:
  - "https://tanstack.com/router/latest/docs/routing/file-based-routing"
---

# 用文件组成路由树

> 创建 Issue 列表和详情页，理解文件名、路径参数和类型推断如何连在一起。

**Outcome:** 能创建 /issues/$issueId 路由并类型安全地读取参数。

## 文件名就是路由设计

在文件路由中，$issueId 会变成必填路径参数。createFileRoute 的字符串由路由生成器校验，它不只是一个普通字符串。

File: `src/routes/issues/$issueId.tsx`

```tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/issues/$issueId')({
  component: IssuePage,
})

function IssuePage() {
  const { issueId } = Route.useParams()
  return <h1>Issue #{issueId}</h1>
}
```

## 链接也参与类型检查

当 to 包含 $issueId 时，Link 会要求 params。参数缺失会在编译期暴露，而不是等用户点击后才发现。

## 实践与验证

### 完成检查点

列表页可以链接到 `/issues/$issueId`，详情页通过 Route API 得到类型化参数。

### 动手练习

增加 `/issues/$issueId/edit` 子路由，并复用父级 issueId 参数生成返回详情页的 Link。

### 验证方法

故意给 Link 传错参数名时 TypeScript 应失败；使用正确 issueId 后页面应显示对应详情。

### 常见错误

- 从 `window.location` 手工切割路径参数。
- 把参数当成数字而不在边界显式转换。

## Official sources

- https://tanstack.com/router/latest/docs/routing/file-based-routing