頁面

頁面是 Astro 專案 src/pages/ 子目錄下的檔案，用來處理路由、資料載入以及網站內所有頁面的版面。

支援的頁面檔案類型

Astro 支援下列在 src/pages/ 目錄裡的檔案類型：

.astro
.md
.mdx（在安裝 MDX 整合 (EN)的情況下）
.html
.js/.ts（作為端點 (EN)）

基於檔案的路由

Astro 使用基於檔案的路由策略（file-based routing）。每個 src/pages/ 目錄下的檔案，都會根據檔案的路徑，變成網站的端點。

如果你的內容位於內容合集 (EN)或 CMS，也能透過動態路由 (EN)功能，讓單一路由檔案產生多個頁面。

進一步了解 Astro 的路由 (EN)。

連結至頁面

你可以用一般的 HTML <a> 元素連結到你網站的其他頁面。記得使用相對於根網域的網址，而非檔案相對路徑。

舉例來說，如果要從 example.com 的其他頁面連到 https://example.com/authors/sonali/：

閱讀更多<a href="/authors/sonali/">關於 Sonali 的資訊</a>。

Astro 頁面

Astro 頁面使用 .astro 副檔名，支援的功能同 Astro 元件。

---
---
<html lang="zh-TW">
  <head>
    <title>我的首頁</title>
  </head>
  <body>
    <h1>歡迎來到我的網站！</h1>
  </body>
</html>

Astro 頁面必須產生完整的 HTML 文件，因此 Astro 預設會替 src/pages/ 的 Astro 元件加上必要的 <!DOCTYPE html> 和 <head> 標籤（除非檔案已包含這些標籤）。如果不想要這個行為，可以將 Astro 元件標記為局部頁面。

為了避免在每個頁面避免寫相同的 HTML 元素，你可以將常用到的 <head> 和 <body> 移到你自己的版面元件，數量不限。

---
import MySiteLayout from "../layouts/MySiteLayout.astro";
---
<MySiteLayout>
  <p>我的頁面內容包在一層版面裡！</p>
</MySiteLayout>

進一步了解版面元件。

Markdown/MDX 頁面

Astro 也會將任何 src/pages/ 內的 Markdown（.md）檔作為你最後網站的頁面。如果你有安裝 MDX 整合 (EN)的話，它也會對 MDX（.mdx）檔做同樣的事。

:::tip對於包含結構相似且相關的 Markdown 檔（如部落格文章或商品項目）的資料夾，請考慮建立內容合集 (EN)，而不是頁面。:::

Markdown 檔可以使用特殊的 layout frontmatter 屬性指定版面元件，進而將 Markdown 內容包進完整的 <html>...</html> 頁面檔案裡。

---
# Example: src/pages/page.md
layout: ../layouts/MySiteLayout.astro
title: 我的 Markdown 頁面
---
# Title

這是我的網頁，用 **Markdown** 寫的喔！

進一步了解如何在 Astro 使用 Markdown (EN)。

HTML 頁面

擁有 .html 副檔名的檔案可以放置在 src/pages/ 內，直接作為網站的頁面，但要注意 HTML 元件不支援部分 Astro 功能。

自訂 404 錯誤頁面

如要自訂 404 錯誤頁面，可以在 src/pages 新增 404.astro 或 404.md。

建構時會產生 404.html 頁面，大多數的部署服務會找到並使用該檔案。

自訂 500 錯誤頁面

要給隨需算繪 (EN)的頁面顯示的自訂 500 錯誤頁面，請建立 src/pages/500.astro 檔案。這個自訂頁面不適用於預算繪的頁面。

如果算繪這個頁面時發生錯誤，會顯示主機預設的 500 錯誤頁面給訪客。

開發時，如果你有 500.astro，執行時丟出的錯誤會記錄在終端機，而不會顯示在錯誤頁面上。

`error`

src/pages/500.astro 是特殊頁面，會自動為所有在算繪時丟出的錯誤傳遞 error 參數。讓你可以用錯誤的詳細資訊（例如從頁面、從中介層等）向訪客顯示相關資訊。

error 參數可以是任何一種資料型別，這可能會影響你在程式碼中怎麽定義這個值的型別，或是怎麽使用這個值：

---
interface Props {
  error: unknown;
}

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

為了避免敏感資訊在顯示來自 error 參數的內容時洩漏，請考慮先對錯誤求值，然後根據丟出的錯誤回傳合適的內容。比如說你應該避免顯示錯誤的堆疊，因為它包含程式在伺服器上的結構。

局部頁面

:::caution局部頁面應該搭配 htmx 或 Unpoly 這種前端套件一起使用。如果不介意寫低階前端 JavaScript 的話，你也可以使用它。考量到這點，它算是進階功能。

除此之外，如果元件包含 scoped styles 或 scripts，則不應使用局部頁面，因為那些元素不會包含在最終輸出的 HTML。如果需要 scoped styles，最好使用一般非局部的頁面，再搭配知道如何把內容合併到 head 的前端套件。:::

局部頁面是位於 src/pages/ 的頁面元件，但不是用來算繪完整的頁面。

和位於該目錄之外的其他元件一樣，這些檔案不會自動包含 <!DOCTYPE html>、<head>、scoped styles 和 scripts。

由於它們位於 src/pages/ 目錄，產生的 HTML 仍然可透過對應到檔案路徑的網址存取。因此算繪套件（例：htmx、Stimulus、jQuery）能夠在不重新整理或前往新頁面的前提下，於客戶端存取並動態載入 HTML 片段。

局部頁面搭配算繪套件同樣能夠開發動態內容，是不使用 Astro 群島和 <script> 標籤 (EN) 時的替代方案。

能夠匯出給 partial (EN) 的值的頁面檔案（例如 .astro 和 .mdx，但不含 .md）即可標記為局部頁面。

---
export const partial = true;
---
<li>我是局部頁面！</li>

與套件搭配使用

搭配 htmx 這種套件，局部頁面可用來動態更新頁面部分區域。

以下範例中，hx-post 屬性對應到局部頁面的網址，該頁面的內容將會用來更新這個頁面特定的 HTML 元素。

<html>
  <head>
    <title>我的頁面</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">目標在這裡</div>
    
      <button hx-post="/partials/clicked/"
        hx-trigger="click"
        hx-target="#parent-div"
        hx-swap="innerHTML"
      >
        點我！
      </button>
    </section>
  </body>
</html>

對應到檔案路徑的 .astro 局部頁面必須存在，且要明確匯出值，將頁面標記為局部頁面。

---
export const partial = true;
---
<div>我被點了！</div>

細節請見 htmx 文件。

貢獻社群贊助