如何从仓库子目录部署Docusaurus站点（非根目录）

1. 根目录必须保留的文件 #

只有.gitlab-ci.yml需要放在项目根目录，GitLab CI会自动读取根目录的该配置文件执行构建流程。其余项目文件（如你的File1-4）和Docusaurus站点文件都可以放在子目录中。

2. 需要修改的配置文件 #

（1）修正.gitlab-ci.yml配置 #

你当前的CI配置存在混用npm/yarn、命令错误的问题，以下是修正后的配置：

image: node:20 # 使用LTS稳定版Node，避免版本兼容问题
cache:
  paths:
    - website/node_modules/

before_script:
  - cd website
  - npm ci # 用ci确保依赖版本与package-lock.json一致，比install更稳定

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - website/build
  only:
    - main

pages:
  stage: deploy
  script:
    - npm run build -- --output-dir ../public # 直接调用Docusaurus构建命令，指定输出到根目录的public（GitLab Pages要求的目录）
  artifacts:
    paths:
      - public
  only:
    - main

（2）调整Docusaurus站点配置 #

修改website/docusaurus.config.js中的url和baseUrl，适配GitLab Pages的路径规则：

module.exports = {
  // 其他配置...
  url: 'https://jrbauhaus.gitlab.io', // 你的GitLab Pages域名
  baseUrl: '/my-website/', // 你的项目名称，必须以/开头和结尾
  // 其他配置...
};

如果你的站点中引用了本地资源（如图片、自定义组件），确保使用相对路径（如./src/assets/logo.png）而非绝对路径，避免子目录环境下的路径解析错误。

3. 易忽略的注意事项 #

• 依赖工具一致性：全程使用npm或yarn中的一种，不要混用，否则会导致依赖冲突或安装失败。
• 本地预测试：先在本地的website目录执行npm run build，验证能否正常生成构建产物；再手动将产物移到根目录的public文件夹，用npx serve public测试站点能否正常访问，确认无误后再推送到GitLab。
• Node版本兼容性：Docusaurus 3.x对Node 22的支持可能存在问题，建议使用Node 18或20 LTS版本，CI配置中指定对应镜像即可。
• 配置文件路径检查：确保docusaurus.config.js中所有路径相关配置（如themeConfig里的logo路径、plugins的配置路径）都适配子目录结构。

针对你当前构建错误的排查方向 #

你遇到的loadSiteConfig错误，大概率是以下原因：

1. docusaurus.config.js中baseUrl配置错误，或存在绝对路径引用导致解析失败；
2. Node版本过高（v22）与Docusaurus 3.3.2不兼容；
3. 依赖安装不完整，改用npm ci可解决版本不一致问题。

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