安裝 Astro

create astro CLI 指令是從零開始一個新 Astro 專案最快的方法。它會引導你完成設定新 Astro 專案的每個步驟，並讓你從幾個不同的官方起始模板中選擇。

你也可以加上 template 選項來執行 CLI 指令，以使用任何現有的主題或起始模板來開始你的專案。探索我們的主題和起始模板展示，你可以在那裡瀏覽部落格、作品集、文件網站、登陸頁面等主題！

如果你想手動安裝 Astro，請參閱我們的手動安裝指南。

:::tip[線上預覽]想在瀏覽器中試用 Astro 嗎？前往 astro.new 瀏覽我們的起始模板，並在不離開瀏覽器的情況下建立新的 Astro 專案。:::

環境要求

Node.js - v22.12.0 或更高版本。不支援奇數版本，像是 v23。
文字編輯器 - 我們推薦使用 VS Code 搭配我們的官方 Astro 擴充功能。
終端機 - Astro 是透過命令列介面（CLI）來使用的。

瀏覽器相容性

Astro 是使用 Vite 建構的，預設支援具有現代 JavaScript 功能的瀏覽器。完整的參考資料，請參閱 Vite 目前支援的瀏覽器版本清單。

從 CLI 精靈安裝

你可以在電腦的任何地方執行 create astro，所以在開始之前不需要為你的專案建立新的空目錄。如果你還沒有為新專案準備空目錄，CLI 精靈會自動幫你建立一個。

在終端機中執行以下指令來啟動安裝精靈：
- npm
- pnpm
- Yarn
```
# 使用 npm 建立新專案
npm create astro@latest
```
```
# 使用 pnpm 建立新專案
pnpm create astro@latest
```
```
# 使用 yarn 建立新專案
yarn create astro
```
如果一切順利，你會看到成功訊息，然後是一些建議的後續步驟。
現在你的專案已經建立，你可以 cd 進入新的專案目錄來開始使用 Astro。
如果你在 CLI 精靈過程中跳過了「Install dependencies?」的步驟，請務必在繼續之前安裝相依套件。
- npm
- pnpm
- Yarn
```
npm install
```
```
pnpm install
```
```
yarn install
```
你現在可以啟動 Astro 開發伺服器並在建構時看到專案的即時預覽！

CLI 安裝選項

你可以在執行 create astro 指令時加上額外選項以自訂設定過程（例如對所有問題回答「是」、跳過 Houston 動畫）或你的新專案（例如是否安裝 git、新增整合）。

查看所有可用的 create astro 指令選項。

新增整合

你可以在啟動新 Astro 專案的同時，在 create astro 指令中傳遞 --add 參數來安裝任何官方整合 (EN)或支援 astro add 指令的社群整合。

在你的終端機中執行以下指令，替換為任何支援 astro add 指令的整合：

# 建立具有 React 和 Partytown 的新專案
npm create astro@latest -- --add react --add partytown

# 建立具有 React 和 Partytown 的新專案
pnpm create astro@latest --add react --add partytown

# 建立具有 React 和 Partytown 的新專案
yarn create astro --add react --add partytown

使用主題或起始模板

使用 create astro 命令時，你可以加上 --template 參數來基於官方範例或任何 GitHub 儲存庫的 main 分支建立新的 Astro 專案。

在你的終端機中執行以下指令，將官方的 Astro 模板名稱或你想使用的主題的 GitHub 使用者名稱和儲存庫名稱替換進去：

# 使用官方範例建立新專案
npm create astro@latest -- --template <example-name>

# 基於 GitHub 儲存庫的 main 分支建立新專案
npm create astro@latest -- --template <github-username>/<github-repo>

# 使用官方範例建立新專案
pnpm create astro@latest --template <example-name>

# 基於 GitHub 儲存庫的 main 分支建立新專案
pnpm create astro@latest --template <github-username>/<github-repo>

# 使用官方範例建立新專案
yarn create astro --template <example-name>

# 基於 GitHub 儲存庫的 main 分支建立新專案
yarn create astro --template <github-username>/<github-repo>

預設情況下，此指令會使用模板儲存庫的 main 分支。若要使用不同的分支名稱，請將其作為 --template 參數的一部分傳遞：<github-username>/<github-repo>#<branch>。

手動安裝

本指南將帶你逐步手動安裝和設定新的 Astro 專案。

如果你不想使用我們的自動化 create astro CLI 工具，可以按照以下指南自行設定專案。

建立你的目錄

建立一個以你的專案名稱命名的空目錄，然後進入該目錄。
```
mkdir my-astro-project
cd my-astro-project
```
進入新目錄後，建立專案的 package.json 檔案。這是你管理專案相依套件（包括 Astro）的方式。如果你不熟悉這個檔案格式，請執行以下指令來建立一個。
- npm
- pnpm
- Yarn
```
npm init --yes
```
```
pnpm init 
```
```
yarn init --yes
```
安裝 Astro

首先，在專案內安裝 Astro 專案相依套件。

:::note[重要]Astro 必須在本地安裝，而非全域安裝。請確保你沒有執行 npm install -g astro、pnpm add -g astro 或 yarn add global astro。:::
- npm
- pnpm
- Yarn
```
npm install astro
```
```
pnpm add astro
```
```
yarn add astro
```
然後，將 package.json 中任何佔位符的 "scripts" 區段替換為以下內容：
```
{
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
}
```
你將在本指南後續步驟中使用這些腳本來啟動 Astro 並執行其不同的指令。

建立你的第一個頁面

在文字編輯器中，於目錄的 src/pages/index.astro 建立新檔案。這將是專案中你的第一個 Astro 頁面。

在本指南中，複製並貼上以下程式碼片段（包括 --- 虛線）到新檔案中：

---
// 歡迎來到 Astro！三重虛線程式碼圍欄之間的所有內容
// 都是你的「元件 frontmatter」。它永遠不會在瀏覽器中執行。
console.log('這會在你的終端機中執行，而不是瀏覽器！');
---
<!-- 以下是你的「元件模板」。它只是 HTML，但加入了
    一些魔法來幫助你建構出色的模板。 -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

建立你的第一個靜態資源

你也會想要建立 public/ 目錄來存放靜態資源。Astro 總是會在最終建構中包含這些資源，所以你可以安全地從元件模板內部參照它們。

在文字編輯器中，於 public/robots.txt 建立新檔案。robots.txt 是一個簡單的檔案，大多數網站都會包含它來告訴搜尋機器人（如 Google）如何處理你的網站。

在本指南，複製並貼上以下程式碼片段到新檔案中：
```
# 範例：允許所有機器人掃描和索引你的網站。
# 完整語法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
建立 astro.config.mjs

Astro 是使用 astro.config.mjs 來設定的。如果你不需要設定 Astro，這個檔案是可選的，但你可能希望現在就建立它。

在專案根目錄建立 astro.config.mjs，並將下面的程式碼複製到其中：
```
import { defineConfig } from "astro/config";

// https://astro.build/config
export default defineConfig({});
```
如果你想在專案中包含 UI 框架元件 (EN)（如 React、Svelte 等）或使用其他工具（如 MDX 或 Partytown），這裡就是你要手動匯入和設定整合 (EN)的地方。

閱讀 Astro 的 API 設定參考 (EN)以獲取更多資訊。
新增 TypeScript 支援

TypeScript 是使用 tsconfig.json 來設定的。即使你不撰寫 TypeScript 程式碼，這個檔案也很重要，這樣 Astro 和 VS Code 等工具才知道如何理解你的專案。沒有 tsconfig.json 檔案，編輯器不會完全支援某些功能（如 npm 套件匯入）。

如果你確實打算撰寫 TypeScript 程式碼，建議使用 Astro 的 strict 或 strictest 模板。你可以在 astro/tsconfigs/ 查看和比較三種模板設定。

在專案根目錄建立 tsconfig.json，並將下面的程式碼複製到其中。（你可以使用 base、strict 或 strictest 做為 TypeScript 模板）：
```
{
  "extends": "astro/tsconfigs/base"
}
```
閱讀 Astro 的 TypeScript 設定指南 (EN)以獲取更多資訊。
後續步驟

如果你已按照上述步驟操作，你的專案目錄現在應該看起來像這樣：
- 目錄node_modules/
  - …
- 目錄public/
  - robots.txt
- 目錄src/
  - 目錄pages/
    index.astro
- astro.config.mjs
- package-lock.json 或 yarn.lock、pnpm-lock.yaml 等
- package.json
- tsconfig.json
你現在可以啟動 Astro 開發伺服器，並在建構時看到專案的即時預覽！

貢獻社群贊助