用途
路径参数（Path Params）用于把 URL 中的动态片段捕获为具名变量，是 TanStack Router 中构建动态路由的基础能力。参数在路由路径中以 $ 前缀定义。
主要能力
动态段
以 $ 前缀的段会捕获直到下一个 / 之前的文本。例如路由 /posts/$postId 中，params.postId 为字符串，类型完全推断，无需手动标注。多个动态段可跨路径层级使用，如 /teams/$teamId/members/$memberId。
Splat / 捕获全部路由
路径以裸 $ 结尾的路由会捕获其后的所有内容，值存放在 _splat 键下。例如 /files/$ 匹配 /files/documents/report.pdf 时，_splat 为 documents/report.pdf。注意：v1 中 * 仍可向后兼容，但 v2 将移除，应始终使用 _splat。
可选参数
可选参数使用 {-$paramName} 语法，该段可以存在也可以不存在；不存在时值为 undefined。例如 /posts/{-$category} 匹配 /posts 时 category 为 undefined，匹配 /posts/tech 时为 "tech"。可组合多个可选参数，如 /posts/{-$category}/{-$slug}。也常用于 i18n 可选语言前缀，如 /{-$locale}/about。
前后缀模式
在 $paramName 外加花括号 {} 可在同一段内允许动态部分前后有文本。前缀示例：/posts/post-{$postId}，URL /posts/post-123 得到 postId 为 "123"。后缀示例：/files/{$fileName}.txt，URL /files/readme.txt 得到 fileName 为 "readme"。也可组合前后缀，如 /users/user-{$userId}.json。
使用方式
导航
使用 Link 的 params 属性传参：<Link to="/posts/$postId" params={{ postId }}>。函数形式可保留其他参数：params={(prev) => ({ ...prev, postId })}。编程式导航使用 useNavigate：navigate({ to: '/posts/$postId', params: { postId } })。可选参数通过传入 category: 'tech' 包含，或传入 category: undefined 省略。
在路由组件外读取参数
useParams({ from: '/posts/$postId' }) 可指定来源路由；useParams({ strict: false }) 返回所有可能路由参数的联合类型。
在 loader 和 beforeLoad 中读取
beforeLoad 和 loader 的回调均可通过 { params } 访问参数，例如 params.postId。
允许的字符
默认参数使用 encodeURIComponent 编码。可通过路由配置 pathParamsAllowedCharacters 允许额外字符，可选字符包括：;、:、@、&、=、+、$、,。
适用场景
适用于需要从 URL 提取动态标识（如文章 ID、团队与成员 ID、文件路径、可选分类或语言前缀）的前端路由场景。
限制与常见错误
- 关键：不要将路径参数插值进 to 字符串（如
to={`/posts/${postId}`}），这会破坏类型安全与参数编码，应使用 params 属性。 - 中等：splat 路由应使用 $ 而非 *，捕获值在
_splat下。 - 中等：花括号仅用于前后缀模式和可选参数，基本动态段使用裸 $。
- 路径参数始终解析为字符串。如需数字，可在 loader 或组件中解析，或使用路由的
params.parse与params.stringify进行双向转换。