Fumadocs项目中自定义basePath导致搜索API失效的解决方案

在使用Fumadocs项目时，当开发者在next.config配置文件中设置了自定义的basePath后，发现搜索功能无法正常工作。这是一个典型的前端路由配置与API请求路径不匹配的问题。

问题现象

当开发者在next.config.js中配置了如下的basePath：

const config = {
  basePath: "/help",
  reactStrictMode: true,
  output: "standalone",
};

搜索API仍然会尝试访问默认路径http://localhost:3000/api/search?query=text，而实际上正确的路径应该是http://localhost:3000/help/api/search?query=text。

问题原因

这个问题源于Fumadocs的搜索组件默认使用了相对路径/api/search，而没有自动适配Next.js配置的basePath。在Next.js应用中，basePath会影响所有路由的前缀，但API请求路径需要显式配置才能与之匹配。

解决方案

Fumadocs提供了RootProvider组件来配置全局设置，包括搜索API的路径。开发者可以通过以下方式手动指定搜索API的完整路径：

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      url: "/help/api/search" // 手动指定包含basePath的完整路径
    },
  }}
>
  {children}
</RootProvider>

最佳实践

1. 环境变量管理：建议将basePath值存储在环境变量中，然后在配置文件中统一引用，避免硬编码。

// next.config.js
const basePath = process.env.NEXT_PUBLIC_BASE_PATH || '';

module.exports = {
  basePath,
  // 其他配置...
}

2. 动态配置：在RootProvider中动态构建API路径：

<RootProvider
  search={{
    options: {
      url: `${process.env.NEXT_PUBLIC_BASE_PATH}/api/search`
    },
  }}
>

3. 测试验证：修改配置后，务必测试以下场景：
   • 搜索功能是否正常工作
   • 生产环境和开发环境的表现是否一致
   • 有无其他API请求受到basePath影响

总结

在Next.js项目中配置basePath时，开发者需要注意它会影响所有路由前缀，包括API路由。Fumadocs通过RootProvider提供了灵活的配置方式，开发者可以根据项目需求自定义搜索API的路径。这种设计既保持了框架的灵活性，又为特殊场景提供了解决方案。

对于类似的前端项目，建议在文档中明确说明路由配置与API路径的关系，帮助开发者更好地理解和使用框架功能。