使用GitHub Pages部署Astro时缺少astro.config.mjs文件的问题

问题根源 #

你遇到的情况是因为GitHub提供的Astro模板仅生成了工作流配置文件（deploy.yml）和npm锁文件，没有完整初始化Astro项目的核心结构，导致部署流程找不到必需的astro.config.mjs配置文件。

分步解决方案 #

1. 本地补全Astro项目结构

   • 先将你的GitHub仓库克隆到本地：

     git clone <你的仓库URL>
     cd <仓库名称>
     

   • 在当前目录初始化完整的Astro作品集项目（使用官方模板）：

     npm create astro@latest . -- --template portfolio
     

   • 初始化过程中选择不初始化Git（因为已有仓库），其余选项按需选择即可。这一步会生成包括astro.config.mjs在内的完整Astro项目文件。

2. 调整Astro配置适配GitHub Pages

   • 打开生成的astro.config.mjs，如果存在base字段（比如base: '/你的仓库名/'），直接删除该字段，或设置为base: ''（无自定义域名时无需指定base路径）。
   • 确保配置中的outDir值为dist（Astro默认值，GitHub Pages工作流需要读取该目录的构建产物）。

3. 检查并修复GitHub Pages工作流

   • 打开.github/workflows/deploy.yml，确保工作流包含以下关键步骤：

     name: Deploy to GitHub Pages
     on:
       push:
         branches: [main]
       workflow_dispatch:
     jobs:
       build:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - name: Install dependencies
             run: npm install
           - name: Build site
             run: npm run build
           - name: Deploy to GitHub Pages
             uses: peaceiris/actions-gh-pages@v4
             with:
               github_token: ${{ secrets.GITHUB_TOKEN }}
               publish_dir: ./dist
     

   • 若原有deploy.yml内容缺失，直接替换为上述代码即可。

4. 提交并推送修复

   • 将所有新生成的文件添加到Git：

     git add .
     

   • 提交变更：

     git commit -m "Add complete Astro project files and fix deployment config"
     

   • 推送到GitHub：

     git push origin main
     

后续验证 #

推送完成后，前往GitHub仓库的「Actions」标签页查看工作流是否正常运行。若执行成功，等待数分钟后，在仓库的「Settings」→「Pages」页面即可看到你的作品集网站已部署完成。

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