安裝 Astro

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

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

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

環境要求

Node.js - v18.20.8 或 v20.3.0、v22.0.0 或更高版本。（不支援 v19 和 v21。）
文字編輯器 - 我們推薦使用 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 開發伺服器 (EN)並在建構時看到專案的即時預覽！

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 專案相依套件。

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” 區段替換為以下內容：
package.json
```
{
  "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）如何處理你的網站。

在本指南，複製並貼上以下程式碼片段到新檔案中：
public/robots.txt
```
# 範例：允許所有機器人掃描和索引你的網站。
# 完整語法：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，並將下面的程式碼複製到其中：
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 模板）：
tsconfig.json
```
{
  "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 開發伺服器 (EN)，並在建構時看到專案的即時預覽！

貢獻社群贊助