使用Docusaurus时本地化URL出现异常问题

1. BaseUrl配置不匹配 #

本地开发时baseUrl通常设为/，但部署到Dokku时如果应用挂载在子路径（比如https://your-app.dokku-domain.com/docs/），docusaurus.config.js里的baseUrl未同步修改，会导致语言切换的路由拼接错误，重复追加/en/。

• 检查docusaurus.config.js的baseUrl是否与部署的实际访问路径一致，比如子路径部署时设为/docs/而非/。

2. Dokku的Nginx路由配置缺失 #

Dokku默认的Nginx配置可能未正确处理单页应用的路由规则，导致多语言路径请求返回404，前端路由因此错误解析，重复追加语言前缀。

• 在应用根目录创建.dokku/nginx.conf.snippet文件，添加以下规则确保所有请求转发到index.html：

  location / {
    try_files $uri $uri/ /index.html;
  }
  

• 部署后执行dokku nginx:build-config <app-name>生效配置。

3. 翻译静态文件未完整部署 #

构建或部署过程中可能遗漏了英文翻译的静态文件，导致/en/docs路径下无对应页面，触发404后引发后续路由错误。

• 确认部署脚本执行了完整的多语言构建命令：docusaurus build（会构建所有配置的语言），或分别执行docusaurus build --locale es和docusaurus build --locale en。
• 检查构建后的build目录是否包含en文件夹，且内部有完整的docs等页面文件。

4. 语言切换组件的路由生成逻辑错误 #

若自定义了语言选择组件，手动拼接URL可能未适配部署环境的baseUrl，导致路径错误。

• 改用Docusaurus官方提供的钩子生成切换链接，示例：

  import { useBaseUrlUtils } from '@docusaurus/useBaseUrl';
  
  const LanguageDropdown = () => {
    const { withBaseUrl } = useBaseUrlUtils();
    const enLink = withBaseUrl('/', { locale: 'en' });
    // 渲染下拉菜单，使用enLink作为跳转地址
    return <a href={enLink}>English</a>;
  };
  

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