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

CONTRACT

执行契约

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

适用条件

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

最小实现

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

src/routes/posts/$postId.tsxtsx

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。

terminalbash

pnpm generate-routes
pnpm typecheck

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