---
id: router.file-route
kind: recipe
product: router
framework: react
locale: zh-CN
revision: 2
sourceCheckedOn: "2026-08-03"
versionRange: "^1"
verifiedAgainst: "@tanstack/react-router@1.170.18"
contentModel: 2
packages:
  - "@tanstack/react-router"
tasks:
  - "create-route"
  - "read-path-param"
  - "file-based-routing"
sourceRefs:
  - "https://tanstack.com/router/latest/docs/routing/file-based-routing"
---

# 创建带路径参数的文件路由

> 在 React 应用中创建 /posts/$postId，并从路由实例读取类型安全的 postId。

## 执行契约

- **适用场景:** 项目使用 TanStack Router 文件路由，并需要让 URL 路径标识单个资源。
- **不要使用:** 不要用于可选筛选条件；这类状态应使用经过验证的 search 参数。
- **前置检查:** 先确认路由目录约定、生成插件以及目标参数名称，禁止手改生成的路由树。
- **验证结果:** 运行路由生成与类型检查，再直接刷新一个真实参数 URL；Link 参数拼错时必须产生类型错误。
- **失败模式:** 若参数为 undefined，通常是文件名、Route 路径或 Link 参数键不一致；对照生成路由树，而不是强制断言。
- **安全边界:** 路径参数只提供类型化字符串，不代表资源授权；在服务端数据边界重新校验身份与权限。

## 适用条件

项目已启用 TanStack Router 文件路由，并需要用 URL 路径标识单个资源。

## 最小实现

文件名中的 $postId 声明必填参数。使用 Route.useParams()，不要从 window.location 手动切割。

File: `src/routes/posts/$postId.tsx`

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

export const Route = createFileRoute('/posts/$postId')({
  component: PostPage,
})

function PostPage() {
  const { postId } = Route.useParams()
  return <h1>Post {postId}</h1>
}
```

## 验证

运行路由生成和 TypeScript 检查。不要手动修改 routeTree.gen.ts。

File: `terminal`

```bash
pnpm generate-routes
pnpm typecheck
```

## Official sources

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