使用@tanstack/zod-adapter解析路径参数时，为何数字参数被识别为字符串导致Zod报错？

这个问题其实是路径参数的本质特性导致的——所有URL路径参数在浏览器和路由系统里都是字符串类型，哪怕你在<Link>组件里传入的是数字1234，最终传递到Zod验证器的还是它的字符串形式（比如"1234"），这就和你定义的z.number()类型不匹配，所以Zod会抛出类型错误。

解决方案 #

这里有两种常用的处理方式：

• 方法一：使用Zod的强制转换类型（推荐）
  直接用z.coerce.number()替代z.number()，它会自动尝试把传入的字符串转换成数字，同时验证转换是否有效（比如如果参数是"abc"，依然会报错）：

export const Route = createFileRoute(
  "/route/$one/$two/$three",
)({
  params: zodValidator(
    z.object({
      one: z.coerce.number(), // 替换为coerce.number()
      two: z.string(),
      three: z.string(),
    }),
  ),
  component: RouteComponent,
});

这样当解析到路径参数"1234"时，会被自动转换成数字1234，完全符合你的类型定义，不会再触发Zod错误。

• 方法二：自定义转换与验证（适合特殊需求）
  如果需要自定义错误提示或者更精细的转换逻辑，可以用z.string().transform()配合refine验证：

export const Route = createFileRoute(
  "/route/$one/$two/$three",
)({
  params: zodValidator(
    z.object({
      one: z.string()
        .transform(val => parseInt(val, 10))
        .refine(val => !isNaN(val), { message: "参数one必须是有效的数字" }),
      two: z.string(),
      three: z.string(),
    }),
  ),
  component: RouteComponent,
});

这种方式会先把字符串转成数字，再验证转换结果是否为有效数字，适合需要定制错误信息的场景。

补充说明 #

为什么<Link>里传数字没用？因为路由库在生成URL时，会把所有参数转成字符串拼接进路径，最终的URL是/route/1234/value/otherValue；而当页面加载解析参数时，从URL中提取的1234本质上就是字符串，这是URL的固有特性，和具体的路由库无关。

备注：内容来源于stack exchange，提问作者Talorcan