Astro部署GitHub Pages后图片无法渲染问题求助

首次使用Astro搭建测试站点并部署至GitHub Pages，已遵循官方部署指南操作，但图片完全无法渲染，仅显示alt文本。仓库地址：https://github.com/Mia703/test-project

相关代码片段 #

GitHub工作流配置 #

# Sample workflow for building and deploying an Astro site to GitHub Pages

name: Deploy Astro CI to GitHub Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out your repository using git
        uses: actions/checkout@v4

      - name: Setup and use Node 20
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build with Astro
        run: npm run build --if-present
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v3

图片引用代码 #

const GENPATH = "../../public/";

const project_data = [
    {
        id: 0,
        projectName: "Testimonial Grid Challenge",
        projectDescription:
            "Challenged by Front-end Mentor to build a testimonials grid section using HTML, CSS, and CSS Grid.",
        projectCreationDate: "December 8, 2022",
        projectHashTagCollection: [
            {
                tag: "#Web_Dev",
            },
        ],
        projectGitLink:
            "https://github.com/Mia703/FrontEnd-Mentor----Testimonials-Grid",
        projectLiveLink:
            "https://mia703.github.io/FrontEnd-Mentor----Testimonials-Grid/",
        projectImageCollection: [
            {
                image: GENPATH + "testimonials-1-desktop.png",
                alt: "Testimonial Grid Challenge - Desktop",
            },
            {
                image: GENPATH + "testimonials-2-tablet.png",
                alt: "Testimonial Grid Challenge - Tablet",
            },
            {
                image: GENPATH + "testimonials-3-mobile.png",
                alt: "Testimonial Grid Challenge - Mobile",
            },
        ],
    },
];

HTML中图片使用代码 #

<div class="project-gallery-container">
    {
        projectImageCollection.map((element) => (
            <img
                src={element.image}
                alt={element.alt}
                decoding="async"
                loading="lazy"
                class="gallery-item"
            />
        ))
    }
</div>

问题分析 #

1. 路径错误：使用../../public/相对路径指向图片是错误的——Astro构建时会将public目录下的所有文件直接复制到dist根目录，因此实际图片的访问路径不包含public，也不需要上级目录的相对路径。
2. 子路径适配缺失：GitHub Pages部署在仓库名子路径下（如https://xxx.github.io/test-project/）时，Astro默认的根路径/会指向域名根目录而非子路径，导致图片找不到。

解决方案 #

1. 修正图片路径 #

将GENPATH改为根路径前缀，后续配合Astro的base配置自动适配子路径：

const GENPATH = "/";

const project_data = [
    {
        // ...其他内容不变
        projectImageCollection: [
            {
                image: GENPATH + "testimonials-1-desktop.png",
                alt: "Testimonial Grid Challenge - Desktop",
            },
            // ...其他图片保持相同格式
        ],
    },
];

2. 配置Astro的base路径 #

在项目根目录的astro.config.mjs中添加site和base配置，base值为你的GitHub仓库名称：

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://mia703.github.io', // 你的GitHub Pages域名
  base: '/test-project', // 你的仓库名称
});

3. 验证并重新部署 #

• 本地运行npm run build，检查dist目录下是否存在图片文件，同时查看生成的HTML中图片路径是否为/test-project/testimonials-1-desktop.png格式。
• 提交修改后的代码到GitHub，触发Action重新部署，图片即可正常渲染。

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