diff --git a/src/content/docs/zh-tw/basics/project-structure.mdx b/src/content/docs/zh-tw/basics/project-structure.mdx index 0af3a16c9a4e3..1ac177d606ef9 100644 --- a/src/content/docs/zh-tw/basics/project-structure.mdx +++ b/src/content/docs/zh-tw/basics/project-structure.mdx @@ -118,7 +118,7 @@ Astro 會處理、最佳化並將你的 `src/` 捆起來建立最後瀏覽器會 這裡有[兩種相依性](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file)你可以在 `package.json` 中指定： `dependencies` 和 `devDependencies` 。在大多情況下運作起來相同：Astro 在建立時會需要所有的相依性，而你的套件管理器會下載這兩個。我們推薦將你所有的依賴模組放在 `dependencies` 來開始，並只在你特別需要的時候才使用 `devDependencies` 。 -若需要為你專案建立一個新的 `package.json` 檔案，可以看看[手動安裝](/zh-tw/install-and-setup/#manual-setup)教學來取得協助。 +若需要為你專案建立一個新的 `package.json` 檔案，可以看看[手動安裝](/zh-tw/install-and-setup/#手動安裝)教學來取得協助。 ### `astro.config.mjs` diff --git a/src/content/docs/zh-tw/install-and-setup.mdx b/src/content/docs/zh-tw/install-and-setup.mdx new file mode 100644 index 0000000000000..9def481a85000 --- /dev/null +++ b/src/content/docs/zh-tw/install-and-setup.mdx @@ -0,0 +1,331 @@ +--- +title: 安裝 Astro +sidebar: + label: 安裝 +description: '如何安裝 Astro 並開始一個新專案' +i18nReady: true +banner: + content: | + Astro v5 已經到來！了解如何升級你的網站。 +--- +import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +[`create astro` CLI 指令](#從-cli-精靈安裝)是從零開始一個新 Astro 專案最快的方法。它會引導你完成設定新 Astro 專案的每個步驟，並讓你從幾個不同的官方起始模板中選擇。 + +你也可以加上 `template` 選項來執行 CLI 指令，以使用任何現有的主題或起始模板來開始你的專案。探索我們的[主題和起始模板展示](https://astro.build/themes/)，你可以在那裡瀏覽部落格、作品集、文件網站、登陸頁面等主題！ + +如果你想手動安裝 Astro，請參閱我們的[手動安裝指南](#手動安裝)。 + +:::tip[線上預覽] +想在瀏覽器中試用 Astro 嗎？前往 [astro.new](https://astro.new/) 瀏覽我們的起始模板，並在不離開瀏覽器的情況下建立新的 Astro 專案。 +::: + +## 環境要求 + +- **Node.js** - `v18.20.8` 或 `v20.3.0`、`v22.0.0` 或更高版本。（不支援 `v19` 和 `v21`。） +- **文字編輯器** - 我們推薦使用 [VS Code](https://code.visualstudio.com/) 搭配我們的[官方 Astro 擴充功能](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)。 +- **終端機** - Astro 是透過命令列介面（CLI）來使用的。 + +## 瀏覽器相容性 + +Astro 是使用 Vite 建構的，預設支援具有現代 JavaScript 功能的瀏覽器。完整的參考資料，請參閱 [Vite 目前支援的瀏覽器版本清單](https://vite.dev/guide/build.html#browser-compatibility)。 + +## 從 CLI 精靈安裝 + +你可以在電腦的任何地方執行 `create astro`，所以在開始之前不需要為你的專案建立新的空目錄。如果你還沒有為新專案準備空目錄，CLI 精靈會自動幫你建立一個。 + + +1. 在終端機中執行以下指令來啟動安裝精靈： + + + + ```shell + # 使用 npm 建立新專案 + npm create astro@latest + ``` + + + ```shell + # 使用 pnpm 建立新專案 + pnpm create astro@latest + ``` + + + ```shell + # 使用 yarn 建立新專案 + yarn create astro + ``` + + + + 如果一切順利，你會看到成功訊息，然後是一些建議的後續步驟。 + +2. 現在你的專案已經建立，你可以 `cd` 進入新的專案目錄來開始使用 Astro。 + +3. 如果你在 CLI 精靈過程中跳過了「Install dependencies?」的步驟，請務必在繼續之前安裝相依套件。 + + + + ```shell + npm install + ``` + + + ```shell + pnpm install + ``` + + + ```shell + yarn install + ``` + + + +4. 你現在可以[啟動 Astro 開發伺服器](/zh-tw/develop-and-build/#start-the-astro-dev-server)並在建構時看到專案的即時預覽！ + + +## CLI 安裝選項 + +你可以在執行 `create astro` 指令時加上額外選項以自訂設定過程（例如對所有問題回答「是」、跳過 Houston 動畫）或你的新專案（例如是否安裝 git、新增整合）。 + +查看[所有可用的 `create astro` 指令選項](https://github.com/withastro/astro/blob/main/packages/create-astro/README.md) + +### 新增整合 + +你可以在啟動新 Astro 專案的同時，在 `create astro` 指令中傳遞 `--add` 參數來安裝任何[官方整合](/zh-tw/guides/integrations-guide/)或支援 `astro add` 指令的社群整合。 + +在你的終端機中執行以下指令，替換為任何支援 `astro add` 指令的整合： + + + + ```shell + # 建立具有 React 和 Partytown 的新專案 + npm create astro@latest -- --add react --add partytown + ``` + + + ```shell + # 建立具有 React 和 Partytown 的新專案 + pnpm create astro@latest --add react --add partytown + ``` + + + ```shell + # 建立具有 React 和 Partytown 的新專案 + yarn create astro --add react --add partytown + ``` + + + +### 使用主題或起始模板 + +使用 `create astro` 命令時，你可以加上 `--template` 參數來基於[官方範例](https://github.com/withastro/astro/tree/main/examples)或任何 GitHub 儲存庫的 `main` 分支建立新的 Astro 專案。 + +在你的終端機中執行以下指令，將官方的 Astro 模板名稱或你想使用的主題的 GitHub 使用者名稱和儲存庫名稱替換進去： + + + + ```shell + # 使用官方範例建立新專案 + npm create astro@latest -- --template + + # 基於 GitHub 儲存庫的 main 分支建立新專案 + npm create astro@latest -- --template / + ``` + + + ```shell + # 使用官方範例建立新專案 + pnpm create astro@latest --template + + # 基於 GitHub 儲存庫的 main 分支建立新專案 + pnpm create astro@latest --template / + ``` + + + ```shell + # 使用官方範例建立新專案 + yarn create astro --template + + # 基於 GitHub 儲存庫的 main 分支建立新專案 + yarn create astro --template / + ``` + + + +預設情況下，此指令會使用模板儲存庫的 `main` 分支。若要使用不同的分支名稱，請將其作為 `--template` 參數的一部分傳遞：`/#`。 + +## 手動安裝 + +本指南將帶你逐步手動安裝和設定新的 Astro 專案。 + +如果你不想使用我們的自動化 `create astro` CLI 工具，可以按照以下指南自行設定專案。 + + +1. 建立你的目錄 + + 建立一個以你的專案名稱命名的空目錄，然後進入該目錄。 + + ```bash + mkdir my-astro-project + cd my-astro-project + ``` + + 進入新目錄後，建立專案的 `package.json` 檔案。這是你管理專案相依套件（包括 Astro）的方式。如果你不熟悉這個檔案格式，請執行以下指令來建立一個。 + + + + ```shell + npm init --yes + ``` + + + ```shell + pnpm init + ``` + + + ```shell + yarn init --yes + ``` + + + +2. 安裝 Astro + + 首先，在專案內安裝 Astro 專案相依套件。 + + :::note[重要] + Astro 必須在本地安裝，而非全域安裝。請確保你**沒有**執行 `npm install -g astro`、`pnpm add -g astro` 或 `yarn add global astro`。 + ::: + + + + ```shell + npm install astro + ``` + + + ```shell + pnpm add astro + ``` + + + ```shell + yarn add astro + ``` + + + + 然後，將 `package.json` 中任何佔位符的 "scripts" 區段替換為以下內容： + + ```json title="package.json" del={3} ins={4-6} + { + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "dev": "astro dev", + "build": "astro build", + "preview": "astro preview" + }, + } + ``` + + 你將在本指南後續步驟中使用這些腳本來啟動 Astro 並執行其不同的指令。 + +3. 建立你的第一個頁面 + + 在文字編輯器中，於目錄的 `src/pages/index.astro` 建立新檔案。這將是專案中你的第一個 Astro 頁面。 + + 在本指南中，複製並貼上以下程式碼片段（包括 `---` 虛線）到新檔案中： + + ```astro title="src/pages/index.astro" + --- + // 歡迎來到 Astro！三重虛線程式碼圍欄之間的所有內容 + // 都是你的「元件 frontmatter」。它永遠不會在瀏覽器中執行。 + console.log('這會在你的終端機中執行，而不是瀏覽器！'); + --- + + + +

Hello, World!

+ + + + ``` + +4. 建立你的第一個靜態資源 + + 你也會想要建立 `public/` 目錄來存放靜態資源。Astro 總是會在最終建構中包含這些資源，所以你可以安全地從元件模板內部參照它們。 + + 在文字編輯器中，於 `public/robots.txt` 建立新檔案。`robots.txt` 是一個簡單的檔案，大多數網站都會包含它來告訴搜尋機器人（如 Google）如何處理你的網站。 + + 在本指南，複製並貼上以下程式碼片段到新檔案中： + + ```diff title="public/robots.txt" + # 範例：允許所有機器人掃描和索引你的網站。 + # 完整語法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt + User-agent: * + Allow: / + ``` + +5. 建立 `astro.config.mjs` + + Astro 是使用 `astro.config.mjs` 來設定的。如果你不需要設定 Astro，這個檔案是可選的，但你可能希望現在就建立它。 + + 在專案根目錄建立 `astro.config.mjs`，並將下面的程式碼複製到其中： + + ```js title="astro.config.mjs" + import { defineConfig } from "astro/config"; + + // https://astro.build/config + export default defineConfig({}); + ``` + + 如果你想在專案中包含 [UI 框架元件](/zh-tw/guides/framework-components/)（如 React、Svelte 等）或使用其他工具（如 MDX 或 Partytown），這裡就是你要[手動匯入和設定整合](/zh-tw/guides/integrations-guide/)的地方。 + + 閱讀 Astro 的 [API 設定參考](/zh-tw/reference/configuration-reference/)以獲取更多資訊。 + +6. 新增 TypeScript 支援 + + TypeScript 是使用 `tsconfig.json` 來設定的。即使你不撰寫 TypeScript 程式碼，這個檔案也很重要，這樣 Astro 和 VS Code 等工具才知道如何理解你的專案。沒有 `tsconfig.json` 檔案，編輯器不會完全支援某些功能（如 npm 套件匯入）。 + + 如果你確實打算撰寫 TypeScript 程式碼，建議使用 Astro 的 `strict` 或 `strictest` 模板。你可以在 [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/) 查看和比較三種模板設定。 + + 在專案根目錄建立 `tsconfig.json`，並將下面的程式碼複製到其中。（你可以使用 `base`、`strict` 或 `strictest` 做為 TypeScript 模板）： + + ```json title="tsconfig.json" "base" + { + "extends": "astro/tsconfigs/base" + } + ``` + + 閱讀 Astro 的 [TypeScript 設定指南](/zh-tw/guides/typescript/#setup)以獲取更多資訊。 + +7. 後續步驟 + + 如果你已按照上述步驟操作，你的專案目錄現在應該看起來像這樣： + + + - node_modules/ + - public/ + - robots.txt + - src/ + - pages/ + - index.astro + - astro.config.mjs + - package-lock.json 或 `yarn.lock`、`pnpm-lock.yaml` 等 + - package.json + - tsconfig.json + + +8. 你現在可以[啟動 Astro 開發伺服器](/zh-tw/develop-and-build/#start-the-astro-dev-server)，並在建構時看到專案的即時預覽！ + +