You need to enable JavaScript to run this app. 如何配置Docusaurus使其发布到GitHub Pages Web根目录而非项目子目录
优惠活动
大模型
产品
解决方案
定价
更多

如何配置Docusaurus使其发布到GitHub Pages Web根目录而非项目子目录

Docusaurus v1 部署到GitHub Pages根目录问题解答

发布脚本的默认逻辑说明

你提到的node_modules/docusaurus/lib/publish-gh-pages.js中的核心代码片段如下:

const websiteURL =
  GITHUB_HOST === GITHUB_DOMAIN
    ? `https://${ORGANIZATION_NAME}.github.io/${PROJECT_NAME}` // gh-pages hosted repo
    : `https://${GITHUB_HOST}/pages/${ORGANIZATION_NAME}/${PROJECT_NAME}`; // GitHub enterprise hosting.

为什么默认会部署到项目子目录?

这套脚本逻辑是适配GitHub Pages普通项目仓库的默认部署规则设计的:

  • 对于普通项目仓库,GitHub Pages的默认访问路径就是https://<组织/用户名>.github.io/<项目名>/,不会挂载到域名根路径
  • 脚本会读取你配置的projectName参数,自动把站点访问路径、静态资源的访问前缀都拼接上/${PROJECT_NAME}的路径段
  • 这个行为是默认适配普通仓库的预设逻辑,不属于功能异常。这也是你遇到资源加载问题的根本原因:本地npm run start启动时,站点默认挂载在本地Web服务的根路径,所以<link rel="stylesheet" href="/css/main.css"/>这类资源引用可以正常工作;但发布到子目录场景下,静态资源实际的存储路径是/${PROJECT_NAME}/css/main.css,路径不匹配就会出现加载失败。

如何配置为根目录部署?

不需要修改publish-gh-pages.js的源码,只要匹配GitHub Pages的根路径部署规则,修改Docusaurus站点配置即可实现,目前有两种常用方案:

方案1:使用用户/组织专属根仓库

GitHub默认将名为<组织/用户名>.github.io的仓库识别为根路径部署仓库,这类仓库的内容会直接挂载到https://<组织/用户名>.github.io/域名根路径下,不会追加项目名子目录。配置步骤:

  • 修改website/siteConfig.js中的核心参数:
    • 将organizationName设置为你的组织名/个人用户名
    • 将projectName设置为空字符串''
    • 将url设置为https://<组织/用户名>.github.io,不要追加项目名后缀
  • 保持原有发布流程不变,再次运行发布脚本即可,脚本会自动生成适配根路径的静态资源引用,不会出现路径不匹配导致的404问题。

方案2:给普通项目仓库绑定自定义域名

如果你希望使用自定义域名访问站点,也可以直接给普通项目仓库绑定自定义域名,绑定后GitHub Pages会将站点挂载到自定义域名的根路径下,不再携带项目名子目录,和目前多数开源项目的站点部署效果一致。配置步骤:

  • 完成自定义域名的DNS解析配置,在仓库的Pages设置中绑定对应的自定义域名
  • 修改website/siteConfig.js中的核心参数:
    • 将url设置为你的自定义域名
    • 将projectName设置为空字符串''
  • 运行发布脚本时会自动推送CNAME文件到gh-pages分支,构建的静态资源路径会完全匹配根路径的访问规则。

内容的提问来源于stack exchange,提问作者neubert

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.16 02:24:04