Gitlab Pipeline部署Storybook至Pages子目录遇404问题求助

核心问题分析 #

1. GitLab Pages全量覆盖特性：你的三个CI任务是独立触发的，每次部署会完全替换Pages的内容。比如打Tag时仅生成public/latest，部署后Pages上只有这个目录；合并MR时生成public/next，会覆盖之前的latest目录，导致其他路径404。
2. Storybook资源路径错误：Storybook默认以根路径生成静态资源引用（如/static/css/main.css），但部署到子目录后，浏览器仍从根目录查找资源，无法匹配子目录下的文件，引发404。

解决方案 #

1. 修正Storybook构建的Base路径 #

在每个构建命令中添加--base-path参数，指定对应的子目录，确保资源引用路径正确：

• 针对latest：npm run build:storybook -c .storybook -- --base-path latest
• 针对next：npm run build:storybook -c .storybook -- --base-path next
• 针对test：npm run build:storybook -c .storybook -- --base-path test

2. 实现子目录共存：用独立分支存储Pages内容 #

GitLab Pages不支持增量更新，因此需要将Pages内容存储在独立分支（如pages-branch），每次构建时拉取现有内容、更新对应子目录后再推送回该分支，最后配置Pages从该分支部署。

调整后的.gitlab-ci.yml

image: node:16-alpine

stages:
  - build
  - deploy

cache:
  paths:
    - node_modules/

before_script:
  - npm ci --legacy-peer-deps
  # 配置Git身份用于提交代码
  - git config --global user.name "GitLab CI Bot"
  - git config --global user.email "ci-bot@gitlab.com"
  # 拉取pages-branch分支到public目录，不存在则创建空目录
  - git clone --depth 1 -b pages-branch $CI_REPOSITORY_URL public || mkdir -p public

# 打Tag时更新latest目录
build-latest:
  stage: build
  script:
    - npm run build:storybook -c .storybook -- --base-path latest
    - rm -rf public/latest
    - cp -r storybook-static/* public/latest
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_TAG'

# 合并MR时更新next目录
build-next:
  stage: build
  script:
    - npm run build:storybook -c .storybook -- --base-path next
    - rm -rf public/next
    - cp -r storybook-static/* public/next
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_EVENT_TYPE == "merge"'

# 手动触发更新test目录
build-test:
  stage: build
  script:
    - npm run build:storybook -c .storybook -- --base-path test
    - rm -rf public/test
    - cp -r storybook-static/* public/test
  artifacts:
    paths:
      - public
  when: manual
  only:
    - merge_requests

# 推送更新到pages-branch
deploy-pages:
  stage: deploy
  script:
    - cd public
    - git add .
    - git commit -m "Update pages: $CI_COMMIT_SHA" || echo "No changes to commit"
    # 使用项目令牌推送，需提前在CI变量中配置GITLAB_TOKEN（带仓库写入权限）
    - git push https://$GITLAB_TOKEN@$CI_REPOSITORY_URL pages-branch
  dependencies:
    - build-latest
    - build-next
    - build-test
  rules:
    - if: '$CI_COMMIT_TAG || ($CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_EVENT_TYPE == "merge") || $CI_PIPELINE_SOURCE == "web"'

3. 配置GitLab Pages从pages-branch部署 #

1. 进入项目Settings > Pages
2. 在Deploy from branch区域，选择pages-branch分支，目录选择/public
3. 保存配置，等待部署完成

额外验证点 #

• 确认GITLAB_TOKEN变量已添加到项目CI/CD变量中，且具有仓库写入权限
• 检查pages-branch分支下的public目录，确认对应子目录已更新
• 访问路径应为https://<你的用户名>.gitlab.io/<项目名>/latest（或/next//test），验证资源加载正常

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