页面

页面是位于 Astro 项目 src/pages/ 子目录中的文件。它们负责处理网站中每个页面的路由、数据加载和整体页面布局。

支持的页面文件

Astro 在 src/pages/ 目录中支持以下文件类型

.astro
.md
.mdx（需要安装 MDX 集成）
.html
.js/.ts（作为端点）

基于文件的路由

Astro 利用一种名为基于文件的路由的路由策略。你 src/pages/ 目录中的每个文件都会根据其文件路径成为你网站上的一个端点。

单个文件也可以使用动态路由生成多个页面。这允许你创建页面，即使你的内容位于特殊的 /pages/ 目录之外，例如在内容集合或 CMS 中。

了解更多关于 Astro 中的路由。

页面间的链接

在你的 Astro 页面中编写标准的 HTML <a> 元素来链接到你网站上的其他页面。使用相对于你的根域的 URL 路径作为你的链接，而不是相对文件路径。

例如，要从 example.com 上的任何其他页面链接到 https://example.com/authors/sonali/

Read more <a href="/authors/sonali/">about Sonali</a>.

Astro 页面

Astro 页面使用 .astro 文件扩展名，并支持与 Astro 组件相同的功能。

---
---
<html lang="en">
  <head>
    <title>My Homepage</title>
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

页面必须生成一个完整的 HTML 文档。如果没有明确包含，Astro 默认会为位于 src/pages/ 中的任何 .astro 组件添加必要的 <!DOCTYPE html> 声明和 <head> 内容。你可以通过将组件标记为页面片段来选择退出此行为。

为避免在每个页面上重复相同的 HTML 元素，你可以将通用的 <head> 和 <body> 元素移动到你自己的布局组件中。你可以根据需要使用任意数量的布局组件。

---
import MySiteLayout from "../layouts/MySiteLayout.astro";
---
<MySiteLayout>
  <p>My page content, wrapped in a layout!</p>
</MySiteLayout>

在 Astro 中了解更多关于布局组件的信息。

Markdown/MDX 页面

Astro 还会将 src/pages/ 内的任何 Markdown (.md) 文件视为你最终网站中的页面。如果你安装了 MDX 集成，它也会以同样的方式处理 MDX (.mdx) 文件。

Markdown 文件可以使用特殊的 layout frontmatter 属性来指定一个布局组件，该组件会将其 Markdown 内容包装在一个完整的 <html>...</html> 页面文档中。

---
layout: ../layouts/MySiteLayout.astro
title: My Markdown page
---
# Title

This is my page, written in **Markdown.**

在 Astro 中了解更多关于 Markdown 的信息。

HTML 页面

带有 .html 文件扩展名的文件可以放在 src/pages/ 目录中，并直接用作你网站上的页面。请注意，HTML 组件中不支持某些关键的 Astro 功能。

自定义 404 错误页面

对于自定义 404 错误页面，你可以在 src/pages 中创建一个 404.astro 或 404.md 文件。

这将构建成一个 404.html 页面。大多数部署服务都会找到并使用它。

自定义 500 错误页面

对于按需渲染的页面，要显示自定义 500 错误页面，请创建 src/pages/500.astro 文件。此自定义页面不适用于预渲染页面，且不能被预渲染。

如果渲染此页面时发生错误，你的访问者将看到主机默认的 500 错误页面。

新增于： astro@4.10.3

在开发过程中，如果你有一个 500.astro 文件，运行时抛出的错误会记录在你的终端中，而不是显示在错误浮层中。

`error`

新增于： astro@4.11.0

src/pages/500.astro 是一个特殊的页面，在渲染过程中抛出的任何错误都会自动传递一个 error prop 给它。这允许你使用错误的详细信息（例如，来自页面、中间件等）向访问者显示信息。

error prop 的数据类型可以是任何东西，这可能会影响你在代码中如何输入或使用该值

---
interface Props {
  error: unknown;
}

const { error } = Astro.props;
---
<div>{error instanceof Error ? error.message : "Unknown error"}</div>

为了避免在显示 error prop 的内容时泄露敏感信息，请考虑首先评估错误，并根据抛出的错误返回适当的内容。例如，你应该避免显示错误的堆栈，因为它包含有关你的代码在服务器上如何结构化的信息。

页面片段

新增于： astro@3.4.0

页面片段是位于 src/pages/ 内的页面组件，它们不打算作为完整页面进行渲染。

与此文件夹之外的组件一样，这些文件不会自动包含 <!DOCTYPE html> 声明，也不会包含任何 <head> 内容，例如局部作用域的样式和脚本。

然而，由于它们位于特殊的 src/pages/ 目录中，生成的 HTML 可以通过其文件路径对应的 URL 访问。这使得渲染库（例如 htmx、Stimulus、jQuery）可以在客户端访问它，并在页面上动态加载 HTML 片段，而无需浏览器刷新或页面导航。

页面片段与渲染库结合使用，为在 Astro 中构建动态内容提供了 Astro Islands 和 <script> 标签的替代方案。

可以为 partial 导出值的页面文件（例如 .astro 和 .mdx，但不是 .md）可以标记为页面片段。

---
export const partial = true;
---
<li>I'm a partial!</li>

与库一起使用

页面片段用于使用像 htmx 这样的库来动态更新页面的某个部分。

以下示例显示了一个 hx-post 属性，它被设置为一个页面片段的 URL。来自该页面片段的内容将用于更新此页面上的目标 HTML 元素。

<html>
  <head>
    <title>My page</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
  <body>
    <section>
      <div id="parent-div">Target here</div>

      <button hx-post="/partials/clicked/"
        hx-trigger="click"
        hx-target="#parent-div"
        hx-swap="innerHTML"
      >
        Click Me!
      </button>
    </section>
  </body>
</html>

.astro 片段必须存在于相应的文件路径中，并包含一个将页面定义为片段的导出

---
export const partial = true;
---
<div>I was clicked!</div>

有关使用 htmx 的更多详细信息，请参阅 htmx 文档。

贡献社区赞助