Docusaurus深度链接新标签页打开返回404错误求助

故障排查方向 #

• 检查docusaurus.config.js核心配置：确认url设置为"https://ampersandtarski.github.io"，baseUrl设置为"/"（个人GitHub Pages仓库的baseUrl必须为根路径），配置错误会导致生成的绝对链接与实际部署路径不匹配。
• 验证构建产物的路径结构：执行npm run build后，查看build目录下的文件，比如深度链接/docs/guide对应的build/docs/guide/index.html是否存在，若缺失需检查页面的路由配置是否正确。
• 确认GitHub Pages部署源与完整性：检查仓库的Pages设置，部署源是否为gh-pages分支（docusaurus deploy会自动推送构建产物到该分支），且build目录下的所有文件（包括关键的404.html）都已完整上传，404.html是Docusaurus单页应用路由的 fallback 依赖。
• 排查缓存与部署生效延迟：GitHub Pages存在缓存，可尝试强制刷新页面（Ctrl+F5），或在Pages设置中重新触发部署，等待10-30分钟确认内容是否更新。
• 核对链接格式的一致性：对比站内跳转的相对路径与复制的绝对路径，检查是否存在斜杠多/少、路径拼写错误等问题，比如是否误把https://ampersandtarski.github.io/docs/guide写成https://ampersandtarski.github.io/guide。
• 自定义域名配置检查（若使用）：若绑定了自定义域名，确认CNAME文件位于构建产物的根目录，且GitHub Pages的自定义域名设置、DNS解析记录均正确，域名解析异常可能导致深度路由失效。

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