Cloudflare Pages 部署 404 排查：三篇文章消失的始末

TL;DR

三篇博文（performance-optimization、knowledge-management-tools、mediawiki-guide）在 Cloudflare Pages 上 404。根因：文件名与 slug 不匹配，Astro 在 SSR 模式下动态路由找不到对应 content 条目。

摘要

• 影响：3 篇文章无法在线访问
• 根因：Markdown 文件名与 frontmatter 中隐含 slug 约定不一致
• 修复：重命名文件名使其与 URL 路径匹配

时间线

时间	事件
06-08	构建 22 页成功，3 篇返回 404
06-09	初步排查：本地 preview 正常，线上 404
06-10	确认是 SSR 模式下 slug 解析差异
06-11	重命名文件，重新构建部署

根因分析

Astro 的 Content Collections 根据文件名生成 slug。如果文件名是 my-article.md，slug 就是 my-article，URL 就是 /blog/my-article。

问题出在这三篇文章：

文件名	期望 URL	实际 slug	结果
blog-performance-optimization.md	/blog/performance-optimization	blog-performance-optimization	404
personal-knowledge-management.md	/blog/knowledge-management-tools	personal-knowledge-management	404
building-personal-wiki-with-mediawiki.md	/blog/mediawiki-guide	building-personal-wiki-with-mediawiki	404

本地 SSG 模式下，所有 slug 都会生成对应 HTML 文件，所以不会 404。但 SSR 模式下，Cloudflare Worker 按路径查找 content 条目，找不到就返回 404。

修复方案

方案 1：重命名文件（推荐）

把文件名改成与期望 URL 一致：

mv blog-performance-optimization.md performance-optimization.md
mv personal-knowledge-management.md knowledge-management-tools.md
mv building-personal-wiki-with-mediawiki.md mediawiki-guide.md

方案 2：在 frontmatter 中指定 slug

Astro 6.x 支持在 frontmatter 中指定 slug：

---
title: '性能优化'
slug: 'performance-optimization'
---

但这需要 Astro 6.4+ 的 Content Collections API 支持。

最终采用

方案 1，重命名文件。最简单、最可靠，不依赖版本特性。

教训

• 文件名就是 slug：在 Astro Content Collections 中，文件名直接决定 URL 路径
• SSG 和 SSR 的路由差异：SSG 会为所有 slug 生成文件，SSR 只按请求查找
• 本地 preview 不等于线上：两种模式路由解析逻辑不同

延伸阅读

• Astro Content Collections 文档
• Astro SSG vs SSR 深度解析