diff --git a/src/content/docs/zh-tw/guides/configuring-astro.mdx b/src/content/docs/zh-tw/guides/configuring-astro.mdx deleted file mode 100644 index f3794c6f7808d..0000000000000 --- a/src/content/docs/zh-tw/guides/configuring-astro.mdx +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: 設定 Astro -i18nReady: true ---- -import ReadMore from '~/components/ReadMore.astro' - -要自訂 Astro 怎麽運作，可以在專案加入 `astro.config.mjs` 檔案。這是 Astro 專案常見的檔案，所有官方的範例模板和主題預設都帶有一個。 - -閱讀 Astro 的 [API 設定參考](/zh-tw/reference/configuration-reference/)以完整了解所有支援的設定選項。 - -## Astro 設定檔 - -Astro 設定檔案必須使用 `default` export 匯出設定。建議搭配 `defineConfig` 輔助函式： - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config' - -export default defineConfig({ - // 這邊放你的設定選項... - // https://docs.astro.build/zh-tw/reference/configuration-reference/ -}) -``` - -我們推薦使用 `defineConfig()`，這樣你的 IDE 會自動顯示型別提示，不過這不是必須的。最低限度的有效設定檔案看起來像這樣： - -```js title="astro.config.mjs" -// 範例：最低限度的空設定檔案 -export default {} -``` - -## 支援的設定檔類型 - -Astro 的 JavaScript 設定檔支援幾個格式：`astro.config.js`、`astro.config.mjs`、`astro.config.cjs` 以及 `astro.config.ts`。我們推薦在多數情況下使用 `.mjs`，如果你想要用 TypeScript 的話就用 `.ts`。 - -TypeScript 設定檔的載入是透過 [`tsm`](https://github.com/lukeed/tsm) 處理的，它會遵循專案的 tsconfig 選項。 - -## 解析設定檔的位置 - -Astro 會自動嘗試在專案根目錄解析名稱是 `astro.config.mjs` 的設定檔。如果在專案根目錄找不到設定檔，則會使用 Astro 的預設選項。 - -```bash -# 範例：從 ./astro.config.mjs 讀取設定 -astro build -``` - -如果要明確指定設定檔，可以使用 `--config` 這個 CLI 選項。它總是會以相對於你執行 `astro` CLI 指令的工作目錄的路徑進行解析。 - -```bash -# 範例：從這個檔案讀取設定 -astro build --config my-config-file.js -``` - -## 設定的 IntelliSense - -Astro 推薦在設定檔中使用 `defineConfig()` 輔助函式。`defineConfig()` 提供 IDE 的自動 IntelliSense 功能。就算你的設定檔案不是用 TypeScript 寫的，VSCode 之類的編輯器依然能夠讀取 Astro 的 TypeScript 型別定義，並提供自動的 jsdoc 型別提示。 - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config' - -export default defineConfig({ - // 這邊放你的設定選項... - // https://docs.astro.build/zh-tw/reference/configuration-reference/ -}) -``` - -你也可以透過 JSDoc 標註，手動提供 VSCode 型別定義： - -```js -// astro.config.mjs -export default /** @type {import('astro').AstroUserConfig} */ { - // 這邊放你的設定選項... - // https://docs.astro.build/zh-tw/reference/configuration-reference/ -} -``` - -## 用相對路徑指定檔案 - -如果提供相對路徑到 `root` 或 `--root` CLI 選項，Astro 會解析該相對路徑，而非執行 `astro` CLI 指令的工作目錄。 - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config' - -export default defineConfig({ - // 解析到現在工作目錄下的 "./foo" 資料夾 - root: 'foo' -}) -``` - -Astro 會將所有其他檔案和資料夾的相對路徑字串，解析為相對於專案根目錄： - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config' - -export default defineConfig({ - // 解析到現在工作目錄下的 "./foo" 資料夾 - root: 'foo', - // 解析到現在工作目錄下的 "./foo/public" 資料夾 - publicDir: 'public', -}) -``` - -要用相對於設定檔的路徑指定檔案或資料夾，請使用 `import.meta.url`（除非你是在寫 common.js 格式的 `astro.config.cjs` 檔案）。 - -```js "import.meta.url" -// astro.config.mjs -import { defineConfig } from 'astro/config' - -export default defineConfig({ - // 解析到相對於這個設定檔案的 "./foo" 資料夾 - root: new URL("./foo", import.meta.url).toString(), - // 解析到相對於這個設定檔案的 "./public" 資料夾 - publicDir: new URL("./public", import.meta.url).toString(), -}) -``` - -:::note -設定檔內無法存取 Vite 特有的 `import.meta` 屬性（例如：`import.meta.env` 或 `import.meta.glob`）。針對這些個別案例，我們推薦用 [dotenv](https://github.com/motdotla/dotenv) 或是 [fast-glob](https://github.com/mrmlnc/fast-glob) 之類的替代品。此外，[tsconfig 的路徑別名](https://www.typescriptlang.org/tsconfig#paths)不會被解析，在這個檔案請使用相對路徑引入模組。 -::: - -## 自訂輸出檔名 - -對於 Astro 處理的程式碼，像是引入的 JavaScript 或 CSS 檔案，只要在 `astro.config.*` 檔案的 `vite.build.rollupOptions` 條目使用 [`entryFileNames`](https://rollupjs.org/configuration-options/#output-entryfilenames)、[`chunkFileNames`](https://rollupjs.org/configuration-options/#output-chunkfilenames) 和 [`assetFileNames`](https://rollupjs.org/configuration-options/#output-assetfilenames)，就可以自訂它們的輸出檔名。 - -```js ins={9-11} -// astro.config.mjs -import { defineConfig } from 'astro/config' - -export default defineConfig({ - vite: { - build: { - rollupOptions: { - output: { - entryFileNames: 'entry.[hash].mjs', - chunkFileNames: 'chunks/chunk.[hash].mjs', - assetFileNames: 'assets/asset.[hash][extname]', - }, - }, - }, - }, -}) -``` - -如果你的程式檔有可能因為名稱而受到廣告攔截器影響（如 `ads.js` 或 `google-tag-manager.js`），這可能會有幫助。 - -## 環境變數 - -Astro 會在載入其他檔案前評估設定檔，因此你不能使用 `import.meta.env` 存取在 `.env` 檔設定的環境變數。 - -你可以在設定檔使用 `process.env` 存取其他環境變數，像是由 CLI 設下的。 - -也可以使用 [Vite 的 `loadEnv` 輔助函式](https://main.vite.dev/config/#using-environment-variables-in-config)手動載入 `.env` 檔。 - -:::note -`pnpm` 不允許引入沒在專案中直接安裝的模組。如果你用的是 `pnpm`，則需要安裝 `vite` 才能使用 `loadEnv` 輔助函式。 -```sh -pnpm add vite --save-dev -``` -::: - -```js title="astro.config.mjs" -import { loadEnv } from "vite"; -const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), ""); -``` - -## 設定參考 - -閱讀 Astro 的 [API 設定參考](/zh-tw/reference/configuration-reference/)以完整了解所有支援的設定選項。 diff --git a/src/content/docs/zh-tw/guides/deploy/cloudflare.mdx b/src/content/docs/zh-tw/guides/deploy/cloudflare.mdx deleted file mode 100644 index 8725baf0363fa..0000000000000 --- a/src/content/docs/zh-tw/guides/deploy/cloudflare.mdx +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: 部署你的 Astro 網站至 Cloudflare Pages -description: 如何使用 Cloudflare Pages 將你的 Astro 網站部署到網路上。 -sidebar: - label: Cloudflare -type: deploy -i18nReady: true ---- -import ReadMore from '~/components/ReadMore.astro'; -import { Steps } from '@astrojs/starlight/components'; - -你可以將你的 Astro 項目部署在 [Cloudflare Pages](https://pages.cloudflare.com/)，一個供前端開發人員協作和部署靜態（JAMstack）或 SSR 網站的平臺。 - -本指南包含： - -- [如何使用 Git 部署一個站點](#如何使用-git-部署網站) -- [如何使用 Wrangler 部署網站](#如何使用-wrangler-部署網站) -- [如何部署 SSR 網站](#如何部署-ssr-網站) - -## 前提條件 - -開始之前，你需要： - -- 一個 Cloudflare 帳號，如果還沒有的話，可以在過程中建立免費的 Cloudflare 帳號 -- 把程式碼推到 [GitHub](https://github.com/) 或者 [GitLab](https://about.gitlab.com/) 儲存庫 - -## 如何使用 Git 部署網站 - - -1. 將程式碼推到 git 倉儲（GitHub、GitLab） - -2. 在 Cloudflare Pages 建立新專案。使用以下的建構設定： - - - **Framework preset:** `Astro` - - **Build command:** `npm run build` - - **Build output directory:** `dist` - -3. 點選 **Save and Deploy** 按鈕。 - - -## 如何使用 Wrangler 部署網站 - - -1. 安裝 [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)。 - -2. 使用 `wrangler login` 登入 Cloudflare 帳號並授權 Wrangler。 - -3. 執行你的建構命令。 - -4. 使用 `npx wrangler pages deploy dist` 部署。 - - -```bash -# 安裝 Wrangler CLI（命令列） -npm install -g wrangler -# 透過 CLI 登入 Cloudflare 帳號 -wrangler login -# 執行你的建構命令 -npm run build -# 建立新的部署 -npx wrangler pages deploy dist -``` - -上傳完所有檔案後，Wrangler 會提供一個預覽網址讓你檢查網站。登入 Cloudflare Pages 儀表板時，你就會看到新專案。 - -### 使用 Wrangler 在本地啟用預覽 - -要使預覽正常運作，你必須安裝 `wrangler` - -```bash -pnpm add wrangler --save-dev -``` - -然後就可以將預覽指令碼從 Astro 的內建預覽命令更新為 `wrangler` 了： - -```json title="package.json" -"preview": "wrangler pages dev ./dist" -``` - -## 如何部署 SSR 網站 - -你可以使用 [`@astrojs/cloudflare` 轉接器](/zh-tw/guides/integrations-guide/cloudflare/)將 Astro SSR 站點部署到 Cloudflare Pages。 - -請按照以下步驟設定轉接器。完成後，你可以使用上述文件中的任何方法進行部署。 - -### 快速安裝 - -使用以下 `astro add` 命令新增 Cloudflare 轉接器以在你的 Astro 專案中啟用 SSR。這將安裝轉接器並一併對 `astro.config.mjs` 進行適當的更改。 - -```bash -npx astro add cloudflare -``` - -### 手動安裝 - -如果你想要手動安裝轉接器，請完成以下兩個步驟： - - -1. 使用你喜歡的套件管理器將 `@astrojs/cloudflare` 加到專案的相依套件中。如果你使用 npm 或不確定是哪個管理器，請在終端機執行： - - ```bash - npm install @astrojs/cloudflare - ``` - -2. 將以下內容新增到 `astro.config.mjs` 檔案中： - - ```js title="astro.config.mjs" ins={2, 5-6} - import { defineConfig } from 'astro/config'; - import cloudflare from '@astrojs/cloudflare'; - - export default defineConfig({ - output: 'server', - adapter: cloudflare() - }); - ``` - - -進一步了解 [Astro 的 SSR（伺服器端算繪）](/zh-tw/guides/on-demand-rendering/)。 - -## 故障排除 - -### 客戶端 hydration - -Cloudflare 的 Auto Minify（自動壓縮）功能可能導致客戶端 hydration 失敗。如果你在控制檯中看到 `Hydration completed but contains mismatches`，請確保在 Cloudflare 設定中停用 Auto Minify。 - -### Node.js runtime API - -如果你用 [Cloudflare SSR 轉接器](/zh-tw/guides/integrations-guide/cloudflare/) 的隨需算繪建立專案，而伺服器在建構時失敗，出現如 `[Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.` 的錯誤資訊： - -- 這意味著你在伺服器端環境中使用的某個套件或匯入與 [Cloudflare runtime API](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) 不相容。 - -- 如果你直接匯入 Node.js runtime API，請參考 Astro 關於 Cloudflare 的 [Node.js 相容性](/zh-tw/guides/integrations-guide/cloudflare/#nodejs-compatibility)文件，瞭解如何進一步解決這個問題。 - -- 如果你匯入的套件中包含 Node.js runtime API，請檢查該套件的作者是否支援 `node:*` 的匯入語法。如果不支援，你可能需要找到其他替代套件。