Astro页面路由与入口：文件位置、类型及特殊用法教程

本节目标：搞懂 Astro 的页面文件该放在哪、哪些文件能当页面用，以及文件怎么变成网站里的网址。

前面几章我们认识了组件（Component）。组件是页面里可以复用的小积木。这一章要说的「页面（Page）」，是用户真正能在浏览器里打开的那个完整网页。

你可以把页面理解成「网站的一扇门」。访客输入一个网址，Astro 就找到对应的页面文件，把它变成 HTML 发给浏览器。Astro 里所有页面有一个共同的规矩：页面文件必须放在项目的 src/pages/ 目录里。这不是随意定的，是 Astro 的硬性约定。

页面住在哪里

在 Astro 项目里，src/pages/ 这个文件夹专门用来放页面。Astro 在构建网站时，会去这个目录里翻一遍，把里面的文件一个个变成可以访问的网址。

一个页面文件要承担三件事：

决定自己的网址（靠文件路径，后面会说）。
加载这个页面需要的数据。
拼出整个页面的 HTML 结构。

也就是说，页面文件既是「地址」，又是「内容」，还是「排版」。它比普通组件管的事更多。

Note

src/ 是 source（源代码）的缩写。pages 就是页面的意思。初学者记住：只要是能被直接访问的网页，就放这里。

哪些文件能当页面用

Astro 很灵活，不是只有 .astro 文件能当页面。src/pages/ 目录里支持下面这些类型：

.astro：Astro 自己的组件文件，最常用来写页面。
.md：Markdown 文件，适合写文章、博客。
.mdx：MDX 文件，是 Markdown 的增强版，可以嵌入组件；需要装好 MDX 集成才能用。
.html：纯 HTML 文件，可以直接放进来当页面。
.js / .ts：JavaScript 或 TypeScript 文件，它们不当普通网页，而是当**端点（endpoint）**用。端点不是给人看的页面，而是给程序调用的接口，比如返回一段 JSON 数据。

这五种入口，覆盖了从手写网页到写文章、再到提供数据接口的各种场景。本章先讲最常见的 .astro、.md、.html 和错误页，端点会在后面的数据章节专门讲。

文件即路由：路径就是网址

Astro 用的是「文件路由（file-based routing）」。这个名字听着玄，意思其实特别直白：文件放在什么路径，网页的网址就是什么路径。

比如你的项目里有这样一个文件：

// src/pages/index.astro
---
---
<html lang="zh-CN">
  <head>
    <title>我的主页</title>
  </head>
  <body>
    <h1>欢迎来到我的网站！</h1>
  </body>
</html>

这个 index.astro 会对应网站根网址 https://你的域名/。index 是首页的约定名，相当于这扇门开在最显眼的位置。

你不需要去某个配置文件里写「把这个文件映射到 / 这个网址」。文件放那儿，网址自然就那儿了。这就是文件路由最大的方便：路由规则看得见、摸得着，就是你的文件夹结构。

页面之间怎么互相跳转

在 Astro 页面里，链接到别的页面用的是最普通的 HTML <a> 标签，不需要任何框架专属的链接组件。

<!-- src/pages/index.astro -->
<p>了解更多 <a href="/about/">关于 Astro</a> 的内容。</p>

这里有个初学者特别容易踩的坑：href 要写相对于网站根目录的网址路径，不要写相对于当前文件的路径。

举个例子，你在 src/pages/about/ 目录下放了一个 index.astro，想链接到 src/pages/contact.astro。正确的写法是 href="/contact/"，而不是 href="../contact/"。因为浏览器访问的是网址，不是硬盘上的文件位置。网址永远从根目录 / 算起。

Tip

养成习惯：写站内链接时，先想「访客在浏览器地址栏看到的网址是什么」，就把那个网址填进 href。这样就很少出错。

Astro 页面自动补全 HTML 外壳

写 .astro 页面时，有一个贴心的小机制。一个页面必须输出一份完整的 HTML 文档（包含 <!DOCTYPE html>、<head>、<body> 这些）。但如果你在 src/pages/ 里的 .astro 文件没写这些，Astro 会自动帮你补上 <!DOCTYPE html> 和必要的 <head> 内容。

当然，绝大多数情况下我们不会每个页面都手写一遍 <html>、<head>、<body>，那样太啰嗦。更聪明的做法是把公共的头部、底部、导航抽到一个「布局（Layout）」组件里，然后每个页面套用这个布局。布局的具体用法，下一章会专门讲。

看一个套用布局的页面长啥样：

// src/pages/index.astro
---
import MySiteLayout from "../layouts/MySiteLayout.astro";
---
<MySiteLayout>
  <p>我的页面内容，被包在布局里啦！</p>
</MySiteLayout>

这样，<html>、<head>、导航、底部都在布局里写一次，每个页面只管自己那段独特内容。

Markdown / MDX 页面

如果你在 src/pages/ 里放一个 .md 文件，Astro 也会把它当成页面。这对写博客、写文档特别友好——你只用关心文字内容，排版交给布局。

Markdown 文件可以用一个特殊的 layout 属性，指定用哪个布局组件把它包成完整网页：

---
layout: ../layouts/MySiteLayout.astro
title: 我的 Markdown 页面
---

# 标题

这是用 **Markdown** 写的页面。

这里的 layout 是 Astro 认识的几个特殊属性之一。它会让指定的布局组件把这篇 Markdown 的内容嵌进去，变成一份带 <html> 外壳的完整页面。MDX 文件同理，只是功能更强。

HTML 页面

.html 文件也能直接放进 src/pages/ 当页面用。不过要注意，HTML 组件不支持 Astro 的一些核心特性（比如后面会讲的作用域样式、部分水合等）。所以纯 HTML 页面一般只在你有现成 HTML 片段、又不想改造成 .astro 时才用。

自定义 404 错误页

访客输错网址、找不到页面时，服务器默认会返回一个冷冰冰的 404 错误页。Astro 允许你做一个自己的 404 页面，让访客体验好一点。

做法很简单：在 src/pages/ 里建一个 404.astro（或 404.md）文件。

// src/pages/404.astro
---
---
<html>
  <body>
    <h1>页面走丢了</h1>
    <p>你访问的网址不存在，<a href="/">回到首页</a> 看看吧。</p>
  </body>
</html>

构建后它会生成 404.html，大多数部署平台都会自动认出它并使用。

自定义 500 错误页

比 404 更少见的是 500 错误，那是服务器在「按需渲染（on-demand rendering）」模式下渲染页面时出了内部错误。如果你用了适配器做服务端渲染，可以建一个 src/pages/500.astro 来展示友好的错误提示。

// src/pages/500.astro
---
interface Props {
  error: unknown;
}
const { error } = Astro.props;
---
<div>{error instanceof Error ? error.message : "未知错误"}</div>

这个特殊的页面会自动收到一个 error 属性，里面是被抛出的错误信息。借助它，你可以把错误展示得温和一点。

Warning

500.astro 只在按需渲染的页面上生效，对预先生成好的静态页面无效。另外展示错误时别把完整的错误堆栈直接暴露给访客，那会泄露你服务器的代码结构。

页面局部（Page Partials）

有时候我们想做一种「半截页面」：它不在 src/pages/ 里当完整网页，却又能通过网址被访问到。这种东西叫页面局部（partial）。

局部最常见的用途，是配合 htmx、jQuery 这类前端库，在不刷新整个页面的情况下，动态替换页面上的某一段内容。

把一个 .astro 文件标记为局部，只需加一行导出：

// src/pages/partials/clicked.astro
---
export const partial = true;
---
<div>我被点击了！</div>

加了 export const partial = true 后，这个文件不会自动套上 <!DOCTYPE html> 和 <head>，它就是一段干净的 HTML 碎片，可以通过 /partials/clicked/ 这个网址被前端库取走、塞进页面里。

Note

局部是 .astro 和 .mdx 文件才支持，.md 文件不行。它是群岛架构和 <script> 标签之外，又一种做动态内容的思路。

本章小结

这一章我们看清了 Astro 页面是怎么回事：页面文件都住在 src/pages/，文件类型可以是 .astro、.md、.mdx、.html，还有当端点用的 .js/.ts。文件放在哪，网址就是哪——这就是文件路由。Astro 还会自动补全 HTML 外壳，让我们省心。404 错误页、500 错误页、页面局部，则是三种特殊的页面用法。

下一章我们讲布局（Layouts），看看怎么把每个页面都要重复写的导航、底部抽出来，让写页面变得轻松。

页面 Pages 与多种入口

页面住在哪里

哪些文件能当页面用

文件即路由：路径就是网址

页面之间怎么互相跳转

Astro 页面自动补全 HTML 外壳

Markdown / MDX 页面

HTML 页面

自定义 404 错误页

自定义 500 错误页

页面局部（Page Partials）

本章小结