專案結構

使用 create-astro CLI 精靈來產生你的新 Astro 專案時，就會包含一些檔案和資料夾。至於其他項目則需要由你自己建立並加入到 Astro 既有的檔案結構。

這裡將介紹 Astro 專案是如何組織，且在你的新專案中會找到的一些檔案。

目錄及檔案

標題為 目錄及檔案

Astro 為你的專案準備固有的資料夾安排。每個 Astro 專案的根目錄應該包含下列目錄及檔案：

• src/* - 你的專案原始碼（元件、頁面、樣式等）。
• public/* - 你的非程式碼、未處理的資源（字體、圖示等）。
• package.json - 一個專案列表。
• astro.config.mjs - 一個 Astro 設定檔（建議）。
• tsconfig.json - 一個 TypeScript 設定檔（建議）。

範例專案樹狀圖

標題為 範例專案樹狀圖

一個一般的 Astro 專案目錄應該看起來像這樣：

• 目錄public/

  • robots.txt
  • favicon.svg
  • social-image.png
• 目錄src/

  • 目錄components/

    • Header.astro
    • Button.jsx
  • 目錄content/

    • config.ts
    • 目錄posts/

      • post1.md
      • post2.md
      • post3.md
  • 目錄layouts/

    • PostLayout.astro
  • 目錄pages/

    • 目錄posts/

      • [post].astro
    • about.astro
    • index.astro
    • rss.xml.js
  • 目錄styles/

    • global.css
• astro.config.mjs
• package.json
• tsconfig.json

src/

標題為 src/

你大多數的專案程式碼會放在 src/ 資料夾內，其包含了：

• 頁面
• 版面
• Astro 元件
• 前端元件（React 等）
• 樣式 （CSS、Sass）
• Markdown

Astro 會處理、最佳化並將你的 src/ 捆起來建立最後瀏覽器會看到的網站。不像靜態的 public/ 資料夾，Astro 會幫你建立並處理你 src/ 的檔案。

一些檔案（如 Astro 元件）會被算繪成靜態的 HTML 而不會就所寫的內容傳到瀏覽器上。其他檔案（如 CSS）會被傳到瀏覽器上，但可能會為了效能表現而先被最佳化或捆進其他 CSS 檔案。

提示

雖然這裡提到許多 Astro 社群常見的慣例作法，但保留給 Astro 使用的目錄其實只有 src/pages/ 和 src/content/。你可以依照適合自己的方式，自由決定其他目錄的命名和結構。

src/pages

標題為 src/pages

加入支援的檔案類型到這個資料夾就可以建立網站的頁面路由。

警告

src/pages 在你的 Astro 專案是一個 必須的 子目錄。沒有它，你的網站不會有任何頁面或路由！

src/components

標題為 src/components

元件 是你 HTML 網頁中可重複使用的程式碼。它們可以是 Astro 元件 或是 前端元件 如 React 或 Vue。一般來說會在這個資料夾中組合和組織你專案所有的元件。

這是在 Astro 專案中普遍的慣例作法，但並非必須。就你自己喜好，自由自在地組織你的元件吧！

src/content

標題為 src/content

src/content/ 是保留給 Astro 的目錄，用來儲存內容合集和設定檔。其他檔案不可放在此目錄底下。

src/layouts

標題為 src/layouts

版面是一個 Astro 元件，用來定義由一個或多個頁面共用的 UI 結構。

就如 src/components 一樣，這個目錄是一個普遍慣例作法並非必須。

src/styles

標題為 src/styles

這是一個普遍的慣例作法來儲存你的 CSS 或 Sass 檔案到一個 src/styles 目錄，但並非必須。只要你的樣式被存放在 src/ 目錄內，並且有正確地引入，Astro 就會處理並最佳化這些檔案。

public/

標題為 public/

public/ 目錄是放置那些在 Astro 建立過程中不需要處理的檔案和資源。這些檔案會原封不動地複製到輸出的資料夾內。

這樣的處理讓 public/ 是放置一般資源如圖片和字體或是特殊檔案像是 robots.txt 和 manifest.webmanifest 的理想地方。

你也能將 CSS 和 JavaScript 放到你的 public/ 目錄裡，但要注意的是這些檔案在你最後輸出建立時並不會捆起來或是最佳化。

提示

一個原則，任何你自己寫的 CSS 或 JavaScript 應該待在你的 src/ 目錄裡。

package.json

標題為 package.json

這是 JavaScript 套件管理器用來管理你依賴模組的一個檔案。它也定義了普遍會用來跑 Astro （例如： npm start 和 npm run build ）的腳本。

這裡有兩種相依性你可以在 package.json 中指定： dependencies 和 devDependencies 。在大多情況下運作起來相同：Astro 在建立時會需要所有的相依性，而你的套件管理器會下載這兩個。我們推薦將你所有的依賴模組放在 dependencies 來開始，並只在你特別需要的時候才使用 devDependencies 。

若需要為你專案建立一個新的 package.json 檔案，可以看看手動安裝教學來取得協助。

astro.config.mjs

標題為 astro.config.mjs

這個檔案會在每個入門範本建立且其包含了你 Astro 專案的設定選項。在此你可以指定用哪些整合、建立選項、伺服選項等等。

Astro 的 JavaScript 設定檔案支援幾個檔案格式：astro.config.js、astro.config.mjs、astro.config.cjs 以及 astro.config.ts。我們推薦在多數情況下使用 .mjs，或者如果你想要用 TypeScript 寫設定檔案的話就用 .ts。

TypeScript 設定檔案的讀取是透過 tsm 處理的，並且會遵循你的專案的 tsconfig 選項。

查看設定 Astro 指南來了解更多在設定上的細節。

tsconfig.json

標題為 tsconfig.json

這個檔案會在每個入門範本建立且其包含了你 Astro 專案的 TypeScript 設定選項。若沒有 tsconfig.json 這個檔案的話，部分功能（像是 npm 套件引入）在編輯器中不會被全部支援。

查看 TypeScript 指南來了解更多設定細節。