Skip to content

Latest commit

 

History

History
127 lines (85 loc) · 5.93 KB

project-structure.mdx

File metadata and controls

127 lines (85 loc) · 5.93 KB
Raw
title description i18nReady
專案結構
學習如何用 Astro 構築出一個專案。
true

import { FileTree } from '@astrojs/starlight/components'

使用 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 - layouts/ - PostLayout.astro - pages/ - posts/ - post1.md - post2.md - post3.md - index.astro - styles/ - global.css - astro.config.mjs - package.json - tsconfig.json

src/

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

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

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

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

src/components

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

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

src/content

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

src/layouts

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

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

src/pages

頁面是特殊的元件，用來建立網站的頁面。頁面可以是 Astro 元件，或代表網站部分內容的 Markdown 檔案。

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

src/styles

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

public/

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

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

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

:::tip 一個原則，任何你自己寫的 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 專案的設定選項。在此你可以指定用哪些整合、建立選項、伺服選項等等。

查看設定方法來了解更多在設定上的細節。

tsconfig.json

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

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