﻿---
title: "使用指南 8：把部落格發佈到自己的網域"
description: "說明 Anglefeint 的靜態部署、網域與環境覆寫、建置和圖片檔案、搜尋及公開導出，以及選用 GA4 整合。"
url: "https://demo.anglefeint.com/zh-hant/blog/starter-guide-deployment/"
language: "zh-hant"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# 使用指南 8：把部落格發佈到自己的網域

**版本說明：** build 與 CI doctor 的自動圖片準備從 0.36.2 起支援；使用 0.36.1 時，請先透過 dev 或 `prepare-covers` 準備圖片。

本篇是入門教學的第 8 / 8 篇。[檢視完整教學順序](https://demo.anglefeint.com/zh-hant/blog/starter-guide-1-configure-your-site/#tutorial-order) · [依欄位查設定字典](https://demo.anglefeint.com/zh-hant/blog/config-reference/)。

本機已經能打開部落格後，發佈需要做三件事：確認最終網域、生成完整靜態檔案、讓託管服務用這個網域提供這些檔案。主題不會替你購買網域、修改 DNS 或自動登錄託管平臺。

目前 starter 預設建置靜態網站，不需要正式環境環境一直執行 Node.js，也不需要為了發佈靜態頁面添加 SSR adapter。下面以 npm 專案和預設輸出目錄 `dist/` 為例。

## 1\. 先確定正式網站地址

準備一個由自己管理的網域，例如 `https://blog.example.com`。在 `src/site.config.ts` 現有頂層 `site` 中合併：

```ts
site: {
  url: 'https://blog.example.com',
},
```

填寫最終對外瀏覽的地址，不填 localhost、某篇文章的網址或託管控制臺地址。其他網站資訊保留不變。

這個值會用於生成 canonical、RSS、sitemap、分享圖片和公開內容連結。它不改變本機開發服務地址，也不會把一個尚未綁定的網域自動指向網站。

### 檢查有沒有舊的環境覆寫

如果專案 `.env`、適用的 `.env.*` 檔案或託管建置環境中設定了 `PUBLIC_SITE_URL`，它優先于設定檔案。只改 site.url 但結果仍是舊網域時，應同時檢查這些位置。一般 dev 使用 development 模式，一般 build 使用 production 模式；自訂 `--mode` 時還會讀取對應模式設定，不能只檢查 `.env`。

不需要環境覆寫就移除對應變數，統一使用 site.url；需要區分環境時，在各自建置環境設定正確值。修改後重新建置，不能只在舊產物裡手動改一個連結。

### 使用網域根目錄

目前主題按網域根目錄部署使用，例如 `https://blog.example.com/`。部署到 `https://example.com/my-blog/` 這種子路徑仍需額外調整，不能只設定 Astro base 就認為全部頁面和資源都相容。

選擇託管方式時確認它能提供根目錄網站、靜態目錄的 index.html 和正常的子頁面路徑。如果使用 GitHub Pages，優先按它的網站網域／自訂網域流程部署，不能直接把專案子路徑教學當作本主題已經支援的設定。平臺具體設定參見 [Astro 部署文檔](https://docs.astro.build/en/guides/deploy/)及其中對應的託管指南。

## 2\. 把需要的原始檔案準備完整

部署應使用你自己的部落格專案及實際內容所在分支，不是把主題維護儲存庫的示範內容直接當成個人部落格。原始碼至少包含專案設定、內容、相依清單和需要的資源。

新增或替換本機封面、碎片圖片後，先在本機 dev 或 doctor 中準備回應式檔案，再提交：

*   文章、碎片、自建頁面和 `src/site.config.ts`。
*   文章引用的原圖、public 圖片、圖標和實際需要的音樂等資源。
*   整個 `src/assets/blog/covers/`，包括 manifest.json、generated/ 和使用到的 originals/。
*   `package.json`、`package-lock.json`，以及專案原有 Astro 設定和託管設定。

原圖不一定放在 originals：放在文章旁邊或 public 中的原檔案也要提交。圖片準備細節見[給文章和碎片添加圖片](https://demo.anglefeint.com/zh-hant/blog/starter-guide-images/)。

一般 dev、build 和 doctor（包含 CI）會自動補齊缺少、過期或損壞的衍生圖片，並重用正確的既有檔案。原圖缺失、無效圖片或不安全路徑仍會報錯。明確執行的 `prepare-covers --check` 與設定同步只驗證、不修復。將原圖及整個 `src/assets/blog/covers/` 提交到 Git 可以重用產物，不依賴部署平台保留圖片快取。

基于 Git 建置的部署不需要提交 node\_modules、`.astro` 或 dist；平臺會安裝相依並生成產物。不要把本機的相依目錄作為靜態網站上傳。環境檔案若沒有進入儲存庫，在平臺上設定需要的環境變數；PUBLIC\_ 變數用於公開網站資訊，不適合存放私密憑據。

## 3\. 本機檢查並預覽真正的建置結果

先按 Ctrl+C 停止 dev，確保目前終端機位於專案根目錄，然後執行：

```bash
npm run doctor
npm run preview
```

打開 preview 印出的網址，檢查首頁、文章、圖片、語言選單和文章搜尋。新增語言或開啟選用頁面時，也檢查它們的入口。評論等外部服務需要瀏覽器實際連線才能確認，本機建置通過不會證明遠程權限設定正確。

這些指令的職責不同：

| 指令 | 做什麼 |
| --- | --- |
| `npm run dev` | 本機開發，相關圖片可自動準備；沒有建置後的全文搜尋索引 |
| `npm run doctor` | 包含 CI 的圖片準備、Astro 檢查和建置；About 開啟時還檢查其執行時設定 |
| `npm run check` | 目前 starter 中同樣呼叫 doctor，不必與 doctor 連續重複執行 |
| `npm run build` | 按需補齊圖片衍生資源並建置網站 |
| `npm run preview` | 提供已經建置的 dist，不重新建置、不發佈網站 |

任何檢查或建置失敗時先修復錯誤，不要部署殘留 dist。doctor 成功後已有建置結果，無需緊接著再執行 check 和 build。preview 按 Ctrl+C 停止。

## 4\. 部署完整靜態產物

你可以連線 Git 儲存庫讓平臺建置，也可以本機建置後手動上傳。兩種方式最終都提供同一份靜態輸出。

### 方式一：託管平臺從 Git 建置

在所選平臺連線自己的儲存庫，並設定：

| 專案 | 目前 starter 的設定 |
| --- | --- |
| 建置分支 | 你實際維護部落格內容的分支 |
| 專案根目錄 | 包含該部落格 package.json 的目錄，不一定是整個儲存庫最外層 |
| Node.js | 滿足專案和相依要求，目前 starter 宣告 22.12.0 或更新版本 |
| 安裝 | npm 專案可使用 `npm ci`，需要已提交且與 package.json 一致的 package-lock.json |
| 建置指令 | `npm run build` |
| 輸出目錄 | `dist`，相對於專案根目錄 |

如果平臺自動執行相依安裝，不必重複添加一次安裝指令；如果要求自己寫完整建置腳本，應先安裝再 build。不要在建置腳本裡重複執行 doctor、check、build。

平臺的框架預設、分支和安裝步驟以它的實際設定為準。選擇靜態輸出方式，不需要把 npm run dev 或 npm run preview 作為正式環境啟動指令。

### 方式二：上傳本機建置結果

本機 doctor 成功後，將 `dist/` 的全部內容上傳到託管服務的網站根目錄。如果服務讓你選擇輸出資料夾，就選擇 dist；如果讓你上傳網站檔案，就上傳 dist 裡面的內容，不要額外多套一層 dist 路徑。

除 HTML 外，還要包含 `_astro/`、`_blog-covers/`、`_social/`、搜尋索引以及本次建置實際生成的其他檔案。以底線開頭的目錄不是可以忽略的臨時檔案；只傳 HTML 會導致樣式、腳本、圖片或搜尋缺少。

重新發佈時使用平臺的完整部署／替換機制，避免只覆寫新檔案卻留下已刪除文章、舊分頁或舊語言檔案。刪除本機 Markdown 不會讓手動上傳伺服器上的舊 HTML 自動消失。

## 5\. 在平臺綁定網域，再設定 DNS

在託管平臺中添加要使用的自訂網域，然後按它提供的記錄值，在網域 DNS 管理處添加或修改記錄。根網域與子網域的記錄型別及目標可能不同，應使用平臺給出的實際值，不要照抄範例 IP。

等待平臺確認網域及 HTTPS 證書可用，再通過正式地址打開網站。若同時使用裸網域和 www 等多個地址，選擇一個作為主地址，並在託管側將其他地址重新導向到它，site.url 也填寫主地址。

canonical 只是頁面中繼資訊，不是瀏覽重新導向。主題中的 site.url 不會替你執行 DNS、證書簽發或多網域跳轉；這些由網域和託管設定負責。更換主網域後重新建置並部署，更新仍保留舊網域的環境覆寫值。

## 6\. 發佈後核對頁面和公開輸出

通過正式網域檢查一篇文章的直接連結，刷新後也應能打開；不能只從首頁點進去成功就認為所有路徑都正確。再檢查圖片、程式碼樣式、語言切換和搜尋。僅在 dev 中測試過的功能，需要在已建置網站上重新確認。

主題預設整合這些靜態輸出，不需要再安裝一套相同集成：

| 地址範例 | 用途 |
| --- | --- |
| `/robots.txt` | 提供抓取規則及 sitemap 地址，不是存取權限控制 |
| `/sitemap-index.xml` | 網站地圖入口，連結應使用正式網域 |
| `/zh/rss.xml` | 中文文章訂閱，其他啟用語言替換 zh |
| `/llms.txt` | AI 可讀內容總索引 |
| `/zh/llms.txt`、`/zh/llms-full.txt` | 該語言有導出內容時的索引與全文合集 |
| `/zh/blog/my-first-post/index.md` | 對應公開文章的 Markdown 輸出，範例 slug 換成真實文章 |
| `/zh/fragments/index.md`、`/zh/about/index.md` | 對應頁面啟用且符合導出條件時的公開內容 |

文章 sitemap 更新日期使用 updatedDate，未填時使用 pubDate，不會每次建置偽造新日期。關閉的語言／頁面不應期待有對應公開導出；文章搜尋的 search: false 不等於文章私密，也不會自動禁止其他公開輸出。

AI 導出包含公開文章、啟用的 Fragments 和 About 內容；評論和裝飾工具介面不在導出內文中。實際 noindex 頁面或站外 canonical 頁面不納入導出，用戶自有檔案與生成路徑衝突時會停止建置，不會直接覆寫。導出檔案和發現連結隨重新建置更新，需要一起部署。

這些中繼資訊與文字輸出有助于發現和讀取，不保證搜尋引擎收錄、AI 引用或流量增長。

### 託管回應標頭的區別

建置會在 dist/\_headers 中為 `/:locale/terminal/*` 補充 `X-Robots-Tag: noindex`，保留已有規則，不修改來源 public/\_headers。支援這種檔案格式的託管服務會應用它；其他服務需要等效回應標頭設定。

Astro preview 不會模擬託管平臺的 \_headers 規則。要判斷回應標頭是否生效，應檢查正式服務的回應，不能只看本機檔案存在；無需為了這條規則添加 Node 伺服器。

網域與環境變數的具體優先級見[網站字典](https://demo.anglefeint.com/zh-hant/blog/config-site-chrome/#environment)，公開說明的逐欄位定義見[GA4 與 AI 閱讀補充字典](https://demo.anglefeint.com/zh-hant/blog/config-analytics-ai/#supplement)。

## 7\. 依需求補充 AI 閱讀說明

一般發佈無需增加這項設定。如果想說明網站背景或提供額外資料，可以在設定頂層合併：

```ts
aiReadableContent: {
  notes: '本站記錄個人學習過程，內容可能持續修訂。',
  links: [{ label: '專案主頁', href: 'https://example.com/project' }],
},
```

notes 支援 Markdown，links 每項填寫 label 和 href。連結應為可公開瀏覽的 HTTP(S) 地址；根路徑等相對地址會按網站地址解析。這是公開的網站補充說明，不替換文章內文，也不是給文章增加隱私限制。

按語言覆寫時，使用 `i18n.locales.<locale>.aiReadableContent`。例如讓中文使用自己的說明且不列附加連結：

```ts
i18n: {
  locales: {
    zh: {
      aiReadableContent: {
        notes: '中文内容是作者自己的学习笔记。',
        links: [],
      },
    },
  },
},
```

省略某個欄位繼承全域值；notes: ‘’ 或 links: \[\] 明確隱藏對應部分。補充說明會進入相關索引、全文合集和單篇 Markdown，填寫前確認愿意公開，修改後重新建置。

## 8\. 依需求啟用 GA4 瀏覽統計

預設不載入 Google 統計腳本。需要統計時，先在 Google Analytics 的網頁資料流中取得以 G- 開頭的 Measurement ID；查找位置可參考 [Google 官方說明](https://support.google.com/analytics/answer/9539598)。主題只接受 G- 形式的 ID，不使用數字屬性 ID、GTM 容器 ID或其他識別碼代替。

在設定頂層、與 site 同一級，合併：

```ts
analytics: {
  googleAnalyticsId: 'G-XXXXXXXXXX',
},
```

替換成真實 ID；空字串關閉。格式錯誤會報設定錯誤。一個 ID 可以統計各語言頁面，按路徑區分語言即可；不必每種主題或語言粘一份腳本。

主題只在正式環境建置且已設定 ID 時輸出載入器，dev 不發送。瀏覽器瀏覽 localhost、其子域或回環等本機地址時，載入器跳過上報；使用局域網 IP 或遠程預覽網域瀏覽正式環境建置則可能上報，不要把所有 preview 都當作被排除。

重新部署後，用正式地址瀏覽並檢視 GA4 實時報告。腳本攔截、網路和統計端設定都可能影響結果。不要同時用手動程式碼、GTM 或其他注入工具重複安裝同一統計；本功能沒有附帶同意管理介面，需要時應自行整合相應方案。

## 9\. 部署失敗或線上不對時

| 現象 | 優先檢查 |
| --- | --- |
| npm ci 失敗 | Node／相依要求，以及 package-lock 是否提交並與 package.json 一致 |
| 提示圖片 missing／stale／modified | 一般 build 會自動修復衍生資源；若仍失敗，請檢查原圖與路徑。唯讀 –check 失敗時，先執行準備指令 |
| 建置成功但頁面 404 | 輸出目錄、發佈分支、網站根目錄和目錄 index 支援；是否誤用未調整的子路徑 |
| 首頁能開，文章刷新 404 | 平臺是否提供真實靜態子路徑，是否錯誤地只發佈首頁或套用 SPA 回退 |
| 頁面沒樣式、圖片或搜尋 | 是否完整部署 dist，資源子目錄是否遺漏，路徑是否被改寫 |
| canonical／RSS 仍是範例網域 | site.url、PUBLIC\_SITE\_URL 及建置模式的環境值，是否重新建置部署 |
| 改設定後線上沒變化 | 是否部署了正確專案、分支和最新提交，而不是只修改本機檔案 |
| 刪除文章後舊連結還能瀏覽 | 是否仍殘留舊部署檔案或快取；檢查完整替換與託管快取 |
| GA4 沒有資料 | 是否設定真實 G- ID、使用正式環境建置和非本機地址，腳本是否被攔截 |

日常更新繼續遵循「本機編輯與準備 → 檢查預覽 → 提交原始檔案 → 建置部署」。升級主題見[安裝教學](https://demo.anglefeint.com/zh-hant/blog/starter-guide-1-configure-your-site/)，語言路徑見[讓更多語言的讀者使用部落格](https://demo.anglefeint.com/zh-hant/blog/starter-guide-languages/)。

## 教學導覽與設定查閱

首次發佈到這裡完成。以後可按要修改的內容回看對應教學或查詢設定字典。

[上一篇：讓更多語言的讀者使用部落格](https://demo.anglefeint.com/zh-hant/blog/starter-guide-languages/) · [八篇教學總入口](https://demo.anglefeint.com/zh-hant/blog/starter-guide-1-configure-your-site/#tutorial-order)。

本篇相關欄位：[網域與環境覆寫](https://demo.anglefeint.com/zh-hant/blog/config-site-chrome/)、[GA4 與 AI 閱讀補充](https://demo.anglefeint.com/zh-hant/blog/config-analytics-ai/)、[搜尋資源](https://demo.anglefeint.com/zh-hant/blog/config-search/)。完整路徑、預設值和限制見[設定字典總入口](https://demo.anglefeint.com/zh-hant/blog/config-reference/)。
