AstroJS部署GitHub Pages流水线成功却持续出现404错误求助

问题根源 #

GitHub Pages仅支持静态站点部署，你当前配置的output: "server"和node适配器会生成依赖Node.js运行环境的服务端渲染（SSR）站点，这类站点无法在GitHub Pages的静态托管环境中运行，这就是流水线全绿但页面404的核心原因。

修复步骤 #

1. 修正Astro配置文件 #

修改astro.config.mjs，移除SSR相关配置，切换为静态输出模式：

import { defineConfig } from 'astro/config';
import react from "@astrojs/react";

// https://astro.build/config
export default defineConfig({
  build:{
    site: 'https://my-personal-githubaccount.github.io/',
    // 注意：如果你的仓库是项目仓库（非username.github.io格式），需要添加base路径：
    // base: '/your-repository-name/'
  },
  integrations: [react({ jsxImportSource: '@emotion/react' })],
  output: "static",
});

• 移除了node适配器的导入与配置
• 将output改为"static"（Astro默认值，也可省略）
• 合并了重复的React配置（原plugins中的React配置已整合到integrations）

2. 验证本地构建产物 #

本地执行npm run build，检查生成的dist文件夹：

• 根目录下应包含index.html及其他页面的HTML文件
• 不再出现server文件夹，所有资源均为静态可直接访问的文件

3. 重新部署 #

提交修改后的配置文件到main分支，触发GitHub Actions流水线重新构建部署。等待部署完成后，访问页面即可正常加载。

补充说明 #

如果你的站点确实需要SSR功能，GitHub Pages无法满足需求，建议改用支持Node.js运行环境的平台进行部署。

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