專案結構

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

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

目錄及檔案

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

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

範例專案樹狀圖

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

├── src/
│   ├── components/
│   │   ├── Header.astro
│   │   └-─ Button.jsx
│   ├── layouts/
│   │   └-─ PostLayout.astro
│   └── pages/
│   │   ├── posts/
│   │   │   ├── post1.md
│   │   │   ├── post2.md
│   │   │   └── post3.md
│   │   └── index.astro
│   └── styles/
│       └-─ global.css
├── public/
│   ├── robots.txt
│   ├── favicon.svg
│   └-─ social-image.png
├── astro.config.mjs
├── package.json
└── tsconfig.json

src/

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

• 頁面
• 版面
• Astro components (EN)
• 前端 components （React 等） (EN)
• 樣式 （CSS、Sass） (EN)
• Markdown (EN)

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

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

src/components

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

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

src/layouts

版面是一個特殊的 component 其會將一些內容包進一個更大的網頁版面。這些很常被用來定義網頁如 Astro 頁面 和 Markdown 頁面 (EN)的版面。

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

src/pages

Pages are a special kind of component used to create new pages on your site. A page can be an Astro component, or a Markdown file that represents some page of content for your site.

警告

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

src/styles

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

public/

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

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

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

提示

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

package.json

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

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

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

astro.config.mjs

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

查看設定方法 (EN)來了解更多在設定配置上的細節。

tsconfig.json

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

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