页面

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

¥Pages are files that live in the src/pages/ subdirectory of your Astro project. They are responsible for handling routing, data loading, and overall page layout for every page in your website.

支持的页面文件

¥Supported page files

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

¥Astro supports the following file types in the src/pages/ directory:

.astro
.md
.mdx（使用已安装 MDX 集成）
.html
.js/.ts（如 endpoints）

基于文件的路由

¥File-based routing

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

¥Astro leverages a routing strategy called file-based routing. Each file in your src/pages/ directory becomes an endpoint on your site based on its file path.

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

¥A single file can also generate multiple pages using dynamic routing. This allows you to create pages even if your content lives outside of the special /pages/ directory, such as in a content collection or a CMS.

页面之间的链接

¥Link between pages

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

¥Write standard HTML <a> elements in your Astro pages to link to other pages on your site. Use a URL path relative to your root domain as your link, not a relative file path.

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

¥For example, to link to https://example.com/authors/sonali/ from any other page on example.com:

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

Astro 页面

¥Astro Pages

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

¥Astro pages use the .astro file extension and support the same features as Astro components.

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

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

¥A page must produce a full HTML document. If not explicitly included, Astro will add the necessary <!DOCTYPE html> declaration and <head> content to any .astro component located within src/pages/ by default. You can opt-out of this behavior on a per-component basis by marking it as a partial page.

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

¥To avoid repeating the same HTML elements on every page, you can move common <head> and <body> elements into your own layout components. You can use as many or as few layout components as you’d like.

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

Read more about layout components in Astro.

Markdown/MDX 页面

¥Markdown/MDX Pages

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

¥Astro also treats any Markdown (.md) files inside of src/pages/ as pages in your final website. If you have the MDX Integration installed, it also treats MDX (.mdx) files the same way.

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

¥Markdown files can use the special layout frontmatter property to specify a layout component that will wrap their Markdown content in a full <html>...</html> page document.

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

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

HTML 页面

¥HTML Pages

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

¥Files with the .html file extension can be placed in the src/pages/ directory and used directly as pages on your site. Note that some key Astro features are not supported in HTML Components.

自定义 404 错误页面

¥Custom 404 Error Page

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

¥For a custom 404 error page, you can create a 404.astro or 404.md file in src/pages.

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

¥This will build to a 404.html page. Most deploy services will find and use it.

自定义 500 错误页面

¥Custom 500 Error Page

要为渲染于需求页面显示自定义 500 错误页面，请创建文件 src/pages/500.astro。此自定义页面不适用于预渲染页面，也无法预渲染。

¥For a custom 500 error page to show for pages that are rendered on demand, create the file src/pages/500.astro. This custom page is not available for prerendered pages and can’t be prerendered.

如果渲染此页面时发生错误，则将向访问者显示主机的默认 500 错误页面。

¥If an error occurs rendering this page, your host’s default 500 error page will be shown to your visitor.

Added in: astro@4.10.3

在开发过程中，如果你有 500.astro，则运行时抛出的错误将记录在你的终端中，而不是显示在错误覆盖中。

¥During development, if you have a 500.astro, the error thrown at runtime is logged in your terminal, as opposed to being shown in the error overlay.

`error`

Added in: astro@4.11.0

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

¥src/pages/500.astro is a special page that is automatically passed an error prop for any error thrown during rendering. This allows you to use the details of an error (e.g. from a page, from middleware, etc.) to display information to your visitor.

error prop 的数据类型可以是任何类型，这可能会影响你在代码中键入或使用值的方式：

¥The error prop’s data type can be anything, which may affect how you type or use the value in your code:

---
interface Props {
    error: unknown
}

const { error } = Astro.props
---

<div>{error instanceof Error ? error.message : 'Unknown error'}</div>

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

¥To avoid leaking sensitive information when displaying content from the error prop, consider evaluating the error first, and returning appropriate content based on the error thrown. For example, you should avoid displaying the error’s stack as it contains information about how your code is structured on the server

页面部分

¥Page Partials

Added in: astro@3.4.0

部分页面组件位于 src/pages/ 内，不打算渲染为完整页面。

¥Partials are page components located within src/pages/ that are not intended to render as full pages.

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

¥Like components located outside of this folder, these files do not automatically include the <!DOCTYPE html> declaration, nor any <head> content such as scoped styles and scripts.

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

¥However, because they are located in the special src/pages/ directory, the generated HTML is available at a URL corresponding to its file path. This allows a rendering library (e.g. htmx, Stimulus, jQuery) to access it on the client and load sections of HTML dynamically on a page without a browser refresh or page navigation.

当与渲染库结合使用时，Partials 提供了 Astro 群岛和 <script> 标签的替代方案，用于在 Astro 中构建动态内容。

¥Partials, when combined with a rendering library, provide an alternative to Astro islands and <script> tags for building dynamic content in Astro.

可以导出值（例如 .astro 、 .mdx ）的页面文件可以标记为部分文件。

¥Page files that can export a value (e.g. .astro , .mdx) can be marked as partials.

通过添加以下导出将 src/pages/ 目录中的文件配置为部分文件：

¥Configure a file within the src/pages/ directory to be a partial by adding the following export:

---
export const partial = true;
---

<li>I'm a partial!</li>

export const partial 必须可静态识别。它可以具有以下值：

¥The export const partial must be identifiable statically. It can have the value of:

布尔值 true。
使用 import.meta.env 的环境变量，例如 import.meta.env.USE_PARTIALS。

与库一起使用

¥Using with a library

部分用于使用 htmx 等库动态更新页面的一部分。

¥Partials are used to dynamically update a section of a page using a library such as htmx.

以下示例显示了设置为部分 URL 的 hx-post 属性。部分页面的内容将用于更新该页面上的目标 HTML 元素。

¥The following example shows an hx-post attribute set to a partial’s URL. The content from the partial page will be used to update the targeted HTML element on this page.

<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>
</html>
<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>

.astro 部分必须存在于相应的文件路径中，并且包含将页面定义为部分的导出：

¥The .astro partial must exist at the corresponding file path, and include an export defining the page as a partial:

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

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

¥See the htmx documentation for more details on using htmx.