Astro未构建index.astro致Netlify部署后首页404的修复方法

• 检查首页文件的命名与位置
  Astro默认会将src/pages/index.astro（或.md/.mdx格式）编译为dist/index.html。先确认项目src/pages目录下是否存在正确命名的首页文件，比如是否误命名为home.astro或放置在子文件夹中；如果使用动态路由生成首页，需确保getStaticPaths返回的路径配置为{ params: {}, props: {} }，这样才会生成根目录的index.html。

• 确认Astro构建输出模式
  检查astro.config.js的输出配置，确保未切换到SSR模式（SSR模式不会生成静态index.html），配置应如下：

  export default defineConfig({
    output: 'static', // 确保值为'static'，而非'server'或'hybrid'
  });
  

• 清理缓存后重新构建
  缓存异常可能导致构建产物缺失，执行以下命令清理后重新构建：

  rm -rf node_modules/.cache dist
  npm run build
  

  构建完成后检查dist目录是否生成了index.html。

• 核查Netlify部署配置
  确认Netlify的发布目录确实设置为dist，无拼写错误；若项目存在_redirects文件，检查是否有覆盖首页的重写规则；手动部署时需确认上传的dist目录包含全部构建产物，包括生成的index.html。

• 检查构建脚本是否被修改
  查看package.json中的build脚本，确保未被修改为非默认命令：

  "scripts": {
    "build": "astro build" // 保持默认命令即可
  }
  

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