Docusaurus plugin-client-redirects在GitHub Pages上无法生效的问题求助

核心结论 #

• 无需强制使用main/master分支，gh-pages完全可以作为生产分支，分支类型不是问题根源。
• 路径中的下划线不会导致重定向文件丢失，Docusaurus对含下划线的路径支持正常。

问题排查与修复步骤 #

1. 检查部署脚本是否完整推送build目录所有文件

本地build生成的重定向文件（比如/docs/trex_publish/index.html）推送后消失，大概率是部署流程未同步build目录全部内容：

• 若使用官方docusaurus deploy命令，确认执行时无报错，日志显示所有文件已推送。
• 若用自定义git脚本，确保包含git add .以添加build目录所有文件，示例脚本：

npm run build
cd build
git init
git add .
git commit -m "Deploy docs with redirects"
git push -f git@github.com:<你的用户名>/<仓库名>.git master:gh-pages

2. 确认插件配置语法完整且正确

你提供的配置片段不完整，需确保@docusaurus/plugin-client-redirects的配置在docusaurus.config.js的plugins数组中，语法无遗漏：

plugins: [
  [
    '@docusaurus/plugin-client-redirects',
    {
      redirects: [
        {
          to: '/docs/publish/trex_publish',
          from: '/docs/trex_publish',
        },
        {
          to: '/docs/publish/trex_sandbox_publish',
          from: '/docs/trex_sandbox_publish',
        },
        // 其他重定向规则
      ],
    },
  ],
],

3. 检查GitHub Pages部署设置与_.nojekyll文件

从Jekyll迁移后，需确保GitHub不再用Jekyll处理静态文件：

• 进入仓库Settings -> Pages，确认部署来源是gh-pages分支的Root目录（而非/docs目录）。
• 检查gh-pages分支根目录是否存在_.nojekyll文件。Docusaurus默认会生成该文件，若缺失，手动在项目根目录创建空的_.nojekyll文件，重新build部署即可。此文件用于告知GitHub跳过Jekyll处理，避免文件被忽略。

4. 手动验证重定向文件

• 本地执行npm run build后，进入build/docs/trex_publish目录，打开index.html，确认内容包含Docusaurus生成的重定向代码（如meta标签<meta http-equiv="refresh" content="0; url=/docs/publish/trex_publish" />）。
• 手动推送build目录到gh-pages分支，推送后查看仓库gh-pages分支，确认docs/trex_publish/index.html等重定向文件存在。

内容的提问来源于stack exchange，提问作者Dave Hagen