Next.js 14.2.20迁移FSD后组件导入错误调试求助

1. 缩小故障范围到最小单元 #

• 把所有现有页面简化为仅渲染基础HTML元素（如<div>Test</div>），逐步恢复页面内容，直到触发错误，快速定位到出问题的组件或模块
• 新建极简测试页面（如/test），逐个导入并渲染FSD各模块下的组件，排查单个模块的导入有效性

2. 排查导入导出不匹配问题（最常见原因） #

TypeScript类型兼容不代表运行时导出导入匹配，重点检查：

• 默认/命名导入混用：比如组件用export default MyComponent，但导入时写import { MyComponent } from '...'，反之亦然
• 重导出链式错误：FSD常用index.ts做模块导出汇总，要确认每一层重导出的名称、类型完全正确，比如features/user/index.ts是否正确导出了UserCard组件
• 用全局搜索批量核对：比如搜索export default，对应检查所有导入该组件的语句；或搜索import {，核对目标文件的导出方式

3. 验证FSD路径别名配置 #

FSD依赖路径别名，Next.js配置错误会导致运行时无法解析模块：

• 检查tsconfig.json/jsconfig.json的paths字段，确认别名（如@/features/*、@/shared/*）与实际文件结构完全匹配
• 临时把别名路径替换为相对路径，测试是否能正常运行，排除别名解析问题
• 确认next.config.js中transpilePackages配置包含FSD模块所在路径（如果模块需要额外转译）

4. 检查服务端/客户端组件兼容性 #

Next.js 14的RSC与CSC规则容易引发运行时错误：

• 确认所有客户端组件都添加了'use client'指令，服务端组件未直接导入客户端组件（如需导入，必须用dynamic且设置ssr: false）
• 排查是否存在服务端导出的组件被客户端直接导入的情况，这类问题TypeScript不会报错，但运行时会返回undefined
• 执行next build --debug，查看详细的模块解析日志，定位具体的组件加载失败点

5. 工具辅助定位问题 #

• 用VS Code的「转到定义」功能，检查每个导入的组件是否能正确跳转到定义文件，排除路径拼写错误
• 开启Node.js调试：修改package.json启动命令为"dev": "NODE_ENV=development node --inspect next dev"，用Chrome DevTools附加调试，在错误栈中找到返回undefined的具体组件
• 清理缓存：删除.next、node_modules文件夹，重新安装依赖并构建，排除缓存残留的旧代码干扰

6. 检查FSD层间依赖合规性 #

FSD的层间依赖规则（如shared可被所有层依赖，features不能依赖pages）被破坏会引发加载错误：

• 确认无反向依赖（如features模块导入pages模块属于违规）
• 用madge --circular src/（需先安装madge）扫描代码中的循环依赖，这类问题会导致模块加载异常

内容的提问来源于stack exchange，提问作者Fumée Noire