Astro.js项目Vercel CLI部署正常，GitHub集成触发报404

核心问题分析 #

你遇到的CLI部署正常但GitHub集成部署404的问题，主要源于Astro配置的冗余冲突以及Vercel云端构建与本地CLI构建的环境差异。

针对你的疑问逐一解答 #

1. 问题是否与output: "static"配置有关？ #

是，但不是output: static本身的问题，而是它和vercel适配器的冲突。当Astro设置output: "static"时，会生成纯静态文件，默认输出到dist目录，此时不需要配置vercel适配器——该适配器是为server或hybrid输出模式设计的，用于处理SSR/SSG混合场景。两者结合会导致构建产物的目录结构不符合Vercel静态站点的识别逻辑，云端构建时无法正确找到入口文件，从而出现404。

2. Vercel CLI与GitHub集成处理构建流程是否有差异？ #

有明显差异：

• CLI部署：在本地完成构建后直接上传产物，或自动读取本地配置并同步到Vercel，过程中会复用本地环境的依赖缓存、配置上下文，容错性更高。
• GitHub集成部署：在Vercel云端环境从头执行构建，完全依赖项目在Vercel控制台的配置（构建命令、输出目录等），且云端环境的缓存、变量与本地独立，配置稍有偏差就会导致构建产物无法被正确识别。

3. 是否有遗漏的设置或配置？ #

有，主要是Vercel控制台的构建配置以及Astro的冗余适配器配置，具体看下面的解决步骤。

具体解决步骤 #

步骤1：修正Astro配置文件 #

修改astro.config.mjs，移除vercel适配器，因为静态输出模式不需要它：

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

export default defineConfig({
  integrations: [
    react(),
    tailwind({
      applyBaseStyles: false,
    }),
  ],
  output: "static",
  // 移除vercel适配器相关代码
});

步骤2：配置Vercel项目构建参数 #

进入Vercel控制台，找到你的项目，依次进入「Settings」→「Build & Development Settings」：

• Build Command：设置为npm run build（如果用pnpm/yarn，对应pnpm build或yarn build）
• Output Directory：明确设置为dist（Astro静态输出的默认目录）
• Framework Preset：选择「Astro」，让Vercel自动适配Astro的构建逻辑

步骤3：清除缓存并重新部署 #

在Vercel控制台的「Deployments」页面，找到失败的部署记录，点击「Redeploy」，选择「Clear build cache and redeploy」，避免旧缓存导致的配置不生效问题。

额外检查（可选） #

• 确认.gitignore文件中没有强制排除dist目录（云端构建会自行生成，本地是否提交不影响，但如果有配置错误的忽略规则，可能间接导致问题）
• 检查GitHub仓库的关联分支是否正确，确保触发部署的分支是你推送代码的分支

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