GitLab CI管道与Vite React项目静态文件部署及访问问题咨询

一、项目背景与问题 #

接手Vite+React项目模板，需完成以下目标：

1. 理解GitLab CI管道构建public目录的逻辑，实现自定义mapscript.js的部署
2. 修复修改配置后，首页https://2024.igem.wiki/bielefeld-cebitec/index.html无法访问的问题（仅https://2024.igem.wiki/bielefeld-cebitec/可正常打开）

项目结构 #

├── README.md                       -> 项目说明文档
├── index.html                      -> 项目入口HTML文件
├── package.json                    -> 项目元数据与依赖管理
├── src/
│   ├── components/                 -> UI组件（导航栏、时间线等）
│   ├── App/                        -> React主应用容器
|   |     └── App.tsx
│   ├── contents/                   -> 页面组件
│   │   └── *.tsx                   
│   ├── main.tsx                    -> 应用入口文件
│   ├── pages.ts                    -> 页面定义与路由映射
│   ├── utils/                      -> 工具函数
│   └── vite-env.d.ts               -> TypeScript类型定义
├── tsconfig.json                   -> TypeScript配置
├── tsconfig.node.json              -> Node.js环境TypeScript配置
├── vite.config.ts                  -> Vite构建配置
└── yarn.lock                       -> Yarn依赖锁定文件

初始GitLab CI配置 #

image: node:18.20.0

build:
  stage: build
  cache:
    - key:
        files:
          - yarn.lock
      paths:
        - .yarn-cache/
  before_script:
    - echo 'yarn-offline-mirror ".yarn-cache/"' >> .yarnrc
    - echo 'yarn-offline-mirror-pruning true' >> .yarnrc
    - yarn install --frozen-lockfile
  script:
    - yarn build
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

pages:
  stage: build
  cache:
    - key:
        files:
          - yarn.lock
      paths:
        - .yarn-cache/
  before_script:
    - echo 'yarn-offline-mirror ".yarn-cache/"' >> .yarnrc
    - echo 'yarn-offline-mirror-pruning true' >> .yarnrc
    - yarn install --frozen-lockfile
  script:
    - yarn build
    - cp -a dist/. public/
    - echo '/* /index.html 200' > public/_redirects
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

二、GitLab CI管道完整流程解析 #

这个CI管道包含两个并行的build阶段任务，分别对应不同分支的触发逻辑：

1. build任务（非默认分支触发） #

• 核心作用：仅验证代码是否能正常构建，不执行部署操作
• 执行流程：
  • 使用node:18.20.0作为运行环境，确保依赖兼容性
  • 基于yarn.lock文件缓存.yarn-cache/目录，避免重复下载依赖，加快构建速度
  • before_script：配置yarn离线镜像规则，然后执行yarn install --frozen-lockfile安装锁定版本的依赖，保证构建一致性
  • script：执行yarn build完成项目构建，生成dist目录
  • 触发规则：仅当提交分支不是项目默认分支时运行

2. pages任务（默认分支触发） #

• 核心作用：完成构建并生成GitLab Pages部署所需的产物，最终上线
• 执行流程：
  • 环境、缓存、依赖安装步骤与build任务完全一致
  • script：
    1. yarn build：构建项目生成dist目录
    2. cp -a dist/. public/：将dist目录下的所有文件（包括index.html、静态资源等）复制到public目录——GitLab Pages要求部署产物必须放在public目录下才能识别
    3. echo '/* /index.html 200' > public/_redirects：创建_redirects文件，配置SPA路由规则，所有路径请求都返回index.html的内容，避免单页应用路由跳转时出现404
  • artifacts：将public目录标记为部署产物，GitLab会自动将该目录部署到Pages服务
  • 触发规则：仅当提交分支是项目默认分支时运行

三、问题解决方案 #

1. 自定义mapscript.js部署的正确方式 #

无需修改Vite的publicDir配置，遵循Vite默认规则即可：

• 删除vite.config.ts中的publicDir: 'pubpub'配置，使用默认的public/目录
• 在项目根目录创建public文件夹，将mapscript.js放入其中——Vite执行yarn build时，会自动将public目录下的文件复制到dist目录，后续CI流程会同步到部署产物public目录中

2. 首页index.html访问问题修复 #

问题根源是部署子路径未配置，导致资源路径错误，同时目录复制逻辑可能存在异常：

• 步骤1：配置Vite部署 base 路径
  在vite.config.ts中添加部署子路径配置，适配项目部署的/bielefeld-cebitec/路径：

  import { defineConfig } from 'vite'
  import react from '@vitejs/plugin-react'
  
  export default defineConfig({
    base: '/bielefeld-cebitec/', // 对应你的部署子路径
    plugins: [react()],
    // 保留原有其他配置
  })
  

• 步骤2：恢复CI的目录复制逻辑
  将.gitlab-ci.yml中pages阶段的script恢复为初始的复制逻辑，避免mv命令可能导致的目录结构异常：

  script:
    - yarn build
    - cp -a dist/. public/
    - echo '/* /index.html 200' > public/_redirects
  

• 步骤3：验证与部署
  本地执行yarn build，检查dist目录下是否包含index.html和mapscript.js；提交代码到默认分支触发CI部署，完成后测试两个首页路径是否均可正常访问。

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