Next.js Link组件报错：prop `href`期望string/object却得到undefined

API 探路者

2026-10-4

可能的触发原因

项目编译缓存未清理，注释代码后的新编译结果未生效，仍在运行旧的构建产物
自定义入口文件（_app.js、_document.js、App Router下的全局layout.js）中使用了Link，或你封装的公共导航、面包屑组件内部调用了Link，不在你之前统计的3处直接调用范围内
第三方UI依赖内部封装了Next.js Link组件，你传入给第三方组件的链接参数为undefined，透传后触发报错
存在组件重名冲突：你自己封装了同名Link组件，或路径别名配置问题导致实际导入的不是官方next/link组件
Next.js版本与Link用法不匹配：13+版本Pages Router和App Router的Link分属不同包，混导会触发异常；12及以下版本Link未包裹a标签也可能触发props校验失败

排查解决步骤

第一步先清理缓存重启：删除项目根目录的.next文件夹，再重新启动开发服务，排除缓存导致的旧代码运行问题
第二步排查全局入口和公共组件：检查_app.js/_document.js、全局layout文件，以及所有封装的公共导航类组件，确认所有直接、间接调用Link的位置都传入了有效的href值
第三步排查第三方组件：逐个注释掉引入的第三方导航类组件（如菜单、面包屑、卡片跳转组件等），测试报错是否消失，定位是否是第三方组件接收的链接参数为undefined导致
第四步校验Link导入路径：全局搜索所有import Link的代码行，确认导入路径为next/link（Pages Router）或next/navigation（App Router），没有导入自定义的重名Link组件
第五步打日志精准定位：打开node_modules/next/dist/client/link.js，找到createPropError函数定义，在报错逻辑前添加console.log('异常Link的props：', arguments)，重启服务后查看控制台输出的props内容，即可直接定位到对应的调用链路
第六步兼容版本用法：如果是Next.js 12及以下版本，确保Link组件内部包裹了a标签；如果是13+版本，确认Link用法和所属路由模式匹配。