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

$ 發布 2026-11-13 | | 更新 2026-11-14
上下文: 說明 Anglefeint 的靜態部署、網域與環境覆寫、建置和圖片檔案、搜尋及公開導出,以及選用 GA4 整合。

確認網站地址,完成本機檢查和圖片準備,再部署靜態檔案、綁定網域並核對結果。


輸出
字數 3.9k 詞元 5.1k

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

本篇是入門教學的第 8 / 8 篇。檢視完整教學順序 · 依欄位查設定字典。

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

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

1. 先確定正式網站地址

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

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 部署文檔及其中對應的託管指南。

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

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

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

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

原圖不一定放在 originals:放在文章旁邊或 public 中的原檔案也要提交。圖片準備細節見給文章和碎片添加圖片。

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

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

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

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

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 伺服器。

網域與環境變數的具體優先級見網站字典,公開說明的逐欄位定義見GA4 與 AI 閱讀補充字典。

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

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

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

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

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

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

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

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

預設不載入 Google 統計腳本。需要統計時,先在 Google Analytics 的網頁資料流中取得以 G- 開頭的 Measurement ID;查找位置可參考 Google 官方說明。主題只接受 G- 形式的 ID,不使用數字屬性 ID、GTM 容器 ID或其他識別碼代替。

在設定頂層、與 site 同一級,合併:

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、使用正式環境建置和非本機地址,腳本是否被攔截

日常更新繼續遵循「本機編輯與準備 → 檢查預覽 → 提交原始檔案 → 建置部署」。升級主題見安裝教學,語言路徑見讓更多語言的讀者使用部落格。

教學導覽與設定查閱

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

上一篇:讓更多語言的讀者使用部落格 · 八篇教學總入口。

本篇相關欄位:網域與環境覆寫、GA4 與 AI 閱讀補充、搜尋資源。完整路徑、預設值和限制見設定字典總入口。