在 Next.js 中使用 nuqs createTypedLink 构建类型安全的路径名与搜索参数链接

发布时间:2026/11/23 7:29:37

在 Next.js 中使用 nuqs createTypedLink 构建类型安全的路径名与搜索参数链接 前端状态管理【免费下载链接】next-usequerystateType-safe search params state manager for React frameworks - Like useState, but stored in the URL query string.项目地址https://gitcode.com/gh_mirrors/ne/next-usequerystate点击查看免费下载导读本文基于 nuqsnext-usequerystate仓库中的 registry 组件 next-typed-links 展开讲解如何将 Next.js 15.5 的typedRoutes类型安全路径名与 nuqs 的搜索参数描述符search params descriptor连接起来通过一个createTypedLink工具函数生成路径名 查询串完全类型安全的href用于Link与路由跳转。读完本文你将掌握createTypedLink的用法、它的底层实现原理、urlKeys重映射机制以及如何将其接入到自己的 Next.js 应用中。typedRoutes 与 nuqs两条类型安全体系的交汇Next.js 自 15.5 起提供 typed routes 的预览支持开启后next/link的href、router.push()、router.replace()等 API 中的路径名会由编译器推断拼错路径或给动态路由传错参数都会在编译/类型检查阶段直接报错。但 typed routes 只保证路径名pathname的类型安全URL 查询参数search params仍是宽泛的字符串世界。而 nuqs 的核心价值恰恰在于通过parseAsFloat、parseAsString等解析器描述符把查询参数变成带默认值、带序列化/反序列化逻辑的类型安全状态。createTypedLink就是连接这两套体系的桥梁它把 typed routes 的类型安全路径名与 nuqs 的搜索参数描述符组合成一个函数调用它即可得到完整、类型安全的href。该工具最初以Next.js 15.5 typed routes 预览支持的形式出现在 nuqs-2.5 发布说明 中随后被整理为独立的 registry 组件。前提条件Next.js 15.5.0typed routes 支持的最小版本并在next.config.ts中开启const nextConfig { experimental: { typedRoutes: true } }已安装nuqsNPM:npm install nuqsPNPM:pnpm add nuqsYarn:yarn add nuqsBun:bun add nuqs并完成 NuqsAdapter 的接入配置。createTypedLink 的使用该组件在仓库中以 shadcn registry item 形式发布元数据见 next-typed-links.json它声明依赖next15.5.0与nuqs并把 typed-links.ts 作为唯一源文件安装到~/src/lib/typed-links.ts。你也可以直接把该函数复制到自己的代码库中。第一步定义搜索参数描述符与 URL 键重映射在src/app/map/search-params.ts中先定义坐标的解析器描述符与useQueryStates复用同一份定义保证读写两端一致import { createTypedLink } from /src/lib/typed-links import { parseAsFloat, type UrlKeys } from nuqs/server const coordinates { latitude: parseAsFloat.withDefault(0), longitude: parseAsFloat.withDefault(0) } // Optional remapping for shorter keys const urlKeys: UrlKeystypeof coordinates { latitude: lat, longitude: lng }UrlKeys是 nuqs 提供的辅助类型定义见 defs.ts它把代码中的属性名映射为URL 中实际使用的查询参数名。当你不希望?latitude...这种冗长键名暴露在地址栏时可以用UrlKeystypeof coordinates声明映射类型系统会保证映射键名与描述符键完全一致。第二步创建绑定到路由的链接生成函数// [!code word:createTypedLink] export const getMapLink createTypedLink( /map, // The values here are inferred from your apps routes coordinates, { urlKeys } )createTypedLink的第一个参数是RouteNext.js typed routes 导出的路径名联合类型其取值由你应用的实际路由自动推断——如果传了不存在的路径类型检查会直接报错。第二个参数是搜索参数描述符第三个参数是可选的序列化选项此处传入urlKeys重映射。第三步调用生成类型安全的 href// Usage: getMapLink({ latitude: 12.34, longitude: 56.78 }) // /map?lat12.34lng56.78传入的值会被逐个序列化并拼接到路径后latitude序列化为latlongitude序列化为lng且因为两个解析器都声明了withDefault(0)传参时属性名、类型都会被严格校验。在组件中配合next/link使用import Link from next/link function MapLinks() { return ( Link href{getMapLink({ latitude: 48.86, longitude: 2.35 })} Paris, France /Link ) }底层实现一次 bind 完成的函数组合createTypedLink的实现非常精简完整源码见 typed-links.tsimport type { Route } from next import { createSerializer, type CreateSerializerOptions, type ParserMap } from nuqs/server export function createTypedLinkParsers extends ParserMap( route: Route, parsers: Parsers, options: CreateSerializerOptionsParsers {} ) { const serialize createSerializerParsers, Route, Route(parsers, options) return serialize.bind(null, route) }它的本质是对 nuqs 的createSerializer实现见 serializer.ts做了一层柯里化封装用createSerializerParsers, Route, Route基于描述符与选项创建序列化函数用serialize.bind(null, route)把路由路径名预绑定为第一个参数返回一个只接收 values的新函数。因此getMapLink(values)等价于serialize(route, values)。从类型角度看serialize.bind(null, route)恰好把SerializeFunctionParsers, Route, Route的路径名 值双参签名收窄为仅值签名Route类型因此贯穿始终——这正是路径名与查询参数双双类型安全的来源。序列化器的核心行为从 serializer.ts 可以看到createSerializer生成的函数支持两种调用形态仅传值serialize({ latitude: 12.34 })生成纯查询串createTypedLink用的是这种形态自动带上已绑定的路径传 base 值serialize(/map, values)此时会解析 base 中的已有查询参数并追加/修改/删除null值会删除对应参数。序列化循环中的关键逻辑serializer.ts逐键处理值为undefined时跳过该键getOwn只认自有属性见 url-keys.ts值等于解析器默认值且clearOnDefault默认true时从 URL 中删除该参数避免地址栏被无意义参数塞满否则调用parser.serialize(value)序列化并写入。clearOnDefault是CreateSerializerOptions中唯一直接暴露的 nuqs 全局选项另有urlKeys与processUrlSearchParams见 serializer.ts。当你在第三个参数中传入{ clearOnDefault: false }时即使值与默认值相同也会保留在 URL 中便于分享完整状态。urlKeys 重映射的底层机制createTypedLink的{ urlKeys }选项最终会进入createSerializer。序列化时每个键都经过 getUrlKey 解析export function getUrlKey( urlKeys: PartialRecordstring, string, key: string ): string { return getOwn(urlKeys, key) ?? key }即如果urlKeys中为该键配置了别名就用别名否则回退到原键名。这套机制与useQueryStates、createSearchParamsCache、createSerializer完全一致useQueryStates.ts、cache.ts、loader.ts 均消费同一份UrlKeys类型意味着同一份urlKeys定义可以同时复用于读取状态useQueryStates、服务端预取createSearchParamsCache和生成链接createTypedLink保证 URL 键名在应用各处永远一致。这也解释了为什么原文档建议把描述符与urlKeys单独抽成模块导出它们是整条类型安全链路的共享契约。使用注意事项与适用边界typed routes 是前提createTypedLink的第一个参数类型来自next的Route只有在开启experimental.typedRoutes时才有实际约束力未开启时它退化为宽泛的字符串失去路径名层面的类型检查。绑定语义返回的函数已绑定固定路径适合为每个页面/路由创建专用的链接生成器如果需要在多个路径间复用同一组描述符可以保留createSerializer原函数每次传入不同 base。序列化选项按需配置默认clearOnDefault: true会移除与默认值相等的参数processUrlSearchParams可在输出前对URLSearchParams做二次加工如追加全局参数但该选项的最终 URL 展示与读取端行为需要自行保证一致。版本适配当前仓库中该组件面向 Next.js 15.5 设计如果项目使用更早版本或 React Router可参考发布说明中复用同一序列化技巧的思路自行封装React Router 侧同样有基于类型安全href的实践见 nuqs-2.5.mdx。总结createTypedLink用约 15 行代码完成了两件重要的事把 Next.js typed routes 的路径名类型系统与 nuqs 的搜索参数类型系统缝合在一起并通过bind把双参序列化函数变成即调即用的单参 href 工厂。配合UrlKeys重映射与clearOnDefault等选项它让构造链接和读取状态共享同一套类型安全的描述符契约从根源上消除了拼写错误、键名不一致与类型漂移三类常见 bug。赞分享前端状态管理【免费下载链接】next-usequerystateType-safe search params state manager for React frameworks - Like useState, but stored in the URL query string.项目地址https://gitcode.com/gh_mirrors/ne/next-usequerystate点击查看免费下载相关推荐NuQS与Elasticsearch集成搜索参数构建查询NuQS与Elasticsearch集成搜索参数构建查询 痛点与解决方案 在Next.js应用中构建搜索功能时开发者常面临URL参数管理与Elasticse前端状态管理Iris 路由宏与链式 RouteBuilder用类型化路径参数构建路由的实战指南Iris 路由宏与链式 RouteBuilder用类型化路径参数构建路由的实战指南 导读 在 Iris Web 框架中路由路径支持一种宏macro语KuGouMusicApi 搜索接口中歌手类型参数的使用注意事项KuGouMusicApi 搜索接口中歌手类型参数的使用注意事项 在使用 KuGouMusicApi 进行音乐搜索时开发者可能会遇到搜索歌手类型 typea后端创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/20 22:44:11

思维图高频面试题:新手避坑指南,3招搞定项目落地难题

思维图高频面试题:新手避坑指南,3招搞定项目落地难题 看了一堆教程还是不会写项目?这是很多转岗开发者最真实的痛苦。你以为背熟了API就是会编程,结果一上手真实业务场景,脑子就一片空白。这时候, 思维图(Mental Map)…

2026/11/21 0:04:09

以太网原理与实战:从帧结构到ESP32、STM32踩坑全攻略

以太网这词儿,干网络的人天天挂在嘴边,搞嵌入式的也绕不开它,甚至家里随便拉根网线插电脑上,那个叫“以太网”的图标,背后就是一套跑了四十多年的成熟技术栈。我最早接触以太网还是在学校实验室拿一根交叉线怼两台电脑…

2026/11/23 7:24:42

电工证上岗必备:湖州安监局电工证报考避坑指南

电工证上岗必备:湖州安监局电工证报考避坑指南 你是不是正在为湖州安监局电工证发愁,不知道去哪报名,怕被中介坑?别急,这篇内容专为一线电工、准备报考电工证的朋友量身打造,帮你避开报名坑,搞定上岗必备的电工证。…

2026/11/23 7:24:41

水电安装工是特种工吗?保姆级教程教你复审延期全流程

水电安装工是特种工吗?保姆级教程教你复审延期全流程 证书过期了不知道怎么复审延期?别慌,这篇保姆级教程从实操角度帮你搞定!作为郑州转岗从业者,我深知特种作业操作证对于职业发展的重要性。尤其是水电安装工,很多人误以为不需要特种作业证,实际上根…

2026/11/23 7:24:41

恐高可以考电工证吗通过率揭秘你别被中介忽悠了

恐高可以考电工证吗通过率揭秘你别被中介忽悠了 你怕被中介坑,怕报名流程复杂,怕证书没用,怕考试不过,这些我们都懂。特别是像你这样,可能 恐高 ,但又想考 电工证 ,心里总有疑问—— 恐高可以考电工证吗 ?别急,咱们今天就 揭秘电工证通过率…

2026/11/23 7:24:41

嵩明电工证在哪里办理怎么考才不白交培训费

嵩明电工证在哪里办理怎么考才不白交培训费 怕考不过白交培训费?嵩明电工证在哪里办理?这可能是你最关心的问题,特别是如果你已经报了名,却又担心自己能不能顺利通过。别急,本文会告诉你怎么利用【考前押题】提高通过率,还有一手报考干货,帮你少走弯路…

2026/11/22 0:09:40

高压电工证还能年审吗良心建议来了,学历不高也能考!

高压电工证还能年审吗良心建议来了,学历不高也能考! 你是不是也担心,自己学历不高,根本报不上高压电工证?其实不然,现在政策已经非常明确, 高压电工证还能年审 ,而且只要符合条件, 学历不是门槛 , 良心建议…

2026/11/23 2:38:11

吴江的电工证免费培训怎么报名?官方报名入口全解析

吴江的电工证免费培训怎么报名?官方报名入口全解析 你急需特种作业证才能上岗找工作,但不知道从哪里下手?别急,现在就给你讲明白【吴江的电工证免费培训】到底怎么操作,以及怎么通过 官方报名入口…

2026/11/23 0:26:19

电工证复审肃州区的真实经历:别被中介坑了,自己搞定更靠谱

电工证复审肃州区的真实经历:别被中介坑了,自己搞定更靠谱 不知道去哪报名怕被中介坑?这几乎是每个需要办理或复审电工证的人的真实经历。尤其在肃州区,信息不透明、流程复杂、中介收费高又不靠谱,让很多电工从业者感到头疼。作为一个在应急管理和特种作…

2026/11/23 0:01:38

南宁哪里可以学电工证值不值得考?怕被中介坑?看这篇就够了

南宁哪里可以学电工证值不值得考?怕被中介坑?看这篇就够了 不知道去哪报名怕被中介坑?南宁哪里可以学电工证值不值得考?这是很多想考电工证的朋友最关心的问题。现实中,不少人在选择培训机构时被各种五花八门的广告信息搞得晕头转向,甚至被坑了钱还没拿…

2026/11/23 0:01:38

建设局特种工证怎么查全国通用的复审流程

建设局特种工证怎么查全国通用的复审流程 证书过期了不知道怎么复审延期,这是很多特种作业从业者常遇到的问题。尤其是在洛阳涧西区从事水利工程工作的你,特种作业操作证不仅是上岗的“通行证”,更是保障安全作业的法律底线。如果操作证过期了,不仅影响工…

2026/11/23 0:01:38

电工证跨考政策值不值得考?学历不高也能考的真相

电工证跨考政策值不值得考?学历不高也能考的真相 你是不是也觉得学历不够,报电工证怕被拒?别急,国家安全生产考试网明文规定, 电工证跨考政策 对学历门槛没有硬性限制,只要你年满18岁,身体健康,能通过实操考试,就能报考。关键是, 值不值得考…

2026/11/22 9:39:14

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/22 5:39:03

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑