Next.js结合TypeScript时如何获取:userid格式的动态路由路径参数

Next.js 采用文件系统路由约定，不需要在代码内写:param格式的路由定义，动态路径段通过固定命名规则的文件/文件夹识别，自动解析为对应参数，完全可以实现和Express req.params一致的读取效果，分两种路由模式说明具体实现：

Pages Router（Next.js 旧版路由模式） #

路由定义规则 #

要匹配/users/:userid路径，在pages目录下按如下结构创建文件，动态参数段用[参数名]的格式命名，对应Express的:param写法：

pages/
└── users/
    └── [userid].tsx  // 匹配所有 /users/xxx 格式的路径

参数获取方式 #

• 页面组件内（客户端渲染场景）
  使用next/router导出的useRouter Hook 获取，动态参数挂载在返回对象的query字段上，和查询参数同字段存储，动态路径参数优先级高于同名查询参数：

import { useRouter } from 'next/router'
import type { NextPage } from 'next'

const UserDetail: NextPage = () => {
  const router = useRouter()
  const { userid } = router.query

  // 首次路由水合阶段query可能为空，加判断避免类型报错
  if (typeof userid !== 'string') return <div>加载中</div>

  return <div>当前访问用户ID：{userid}</div>
}

export default UserDetail

• API路由/服务端渲染逻辑内
  API路由、getServerSideProps、getStaticProps等服务端场景中，动态参数直接从请求对象/上下文的query字段读取：

// pages/api/users/[userid].ts
import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const { userid } = req.query
  // 此处userid等价于Express里的req.params.userid
  res.status(200).json({ userId: userid })
}

App Router（Next.js 13+ 推荐路由模式） #

路由定义规则 #

动态段命名规则和Pages Router一致，动态参数用[参数名]包裹，要匹配/users/:userid路径的目录结构如下：

app/
└── users/
    └── [userid]/
        └── page.tsx // 匹配所有 /users/xxx 格式的路径

参数获取方式 #

App Router 明确区分路径参数和查询参数，路径参数统一存在params字段，完全对齐Express req.params的逻辑，不会和?key=value格式的查询参数混淆。

• 服务端组件（App Router默认组件类型）
  直接从页面组件的props中解构params即可，TS类型可直接自定义获得完整提示：

// app/users/[userid]/page.tsx
type PageProps = {
  params: { userid: string }, // 动态路径参数
  searchParams: Record<string, string | string[] | undefined> // ?xxx=格式的查询参数
}

export default function UserDetailPage({ params, searchParams }: PageProps) {
  return <div>当前访问用户ID：{params.userid}</div>
}

• 客户端组件
  使用next/navigation导出的useParams Hook 读取，支持泛型传入参数类型获得TS提示：

'use client'
import { useParams } from 'next/navigation'

export default function UserClientPart() {
  const params = useParams<{ userid: string }>()
  return <div>当前访问用户ID：{params.userid}</div>
}

• Route Handler（原API路由）
  从处理函数的第二个上下文参数中读取params：

// app/api/users/[userid]/route.ts
import { NextResponse } from 'next/server'

type RouteContext = {
  params: { userid: string }
}

export async function GET(req: Request, context: RouteContext) {
  const { userid } = context.params
  return NextResponse.json({ userId: userid })
}

常见问题说明 #

如果目前只能拿到?userid=格式的查询参数，是因为没有按照动态路由的命名规则创建对应文件，Next.js 会把未匹配到动态路由段的参数识别为查询字符串参数，调整文件/文件夹命名为[userid]格式后即可自动解析路径中的动态参数。
如果需要匹配多段路径（比如/users/a/b/c），可以使用捕获所有路由的命名格式[...slug]，此时对应参数类型为string[]，按需调整TS类型定义即可。

内容的提问来源于stack exchange，提问作者dolly60019