﻿---
title: "設定字典：GA4 瀏覽統計、AI 閱讀補充說明"
description: "以實際程式碼說明 GA4 和 AI 閱讀補充欄位的型別、預設值、驗證、輸出位置、語言覆寫與設定邊界。"
url: "https://demo.anglefeint.com/zh-hant/blog/config-analytics-ai/"
language: "zh-hant"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# 設定字典：GA4 瀏覽統計、AI 閱讀補充說明

第一次發佈可讀[部署教學](https://demo.anglefeint.com/zh-hant/blog/starter-guide-deployment/)，其中介紹統計 ID 獲取和公開文字用途。設定檔案位置見[安裝與網站資訊](https://demo.anglefeint.com/zh-hant/blog/starter-guide-1-configure-your-site/)，其他模組從[設定字典總入口](https://demo.anglefeint.com/zh-hant/blog/config-reference/)進入。

這兩組設定寫在 `src/site.config.ts` 頂層，與 site、theme 同級：analytics 是瀏覽統計，aiReadableContent 是公開網站文字補充。它們互不相依，開啟統計不需要填寫 AI 補充，生成公開文字也不需要統計 ID。

## analytics.googleAnalyticsId：GA4 識別碼

| 路徑 | 型別 / 預設值 | 狀態、作用與限制 | 範例值 |
| --- | --- | --- | --- |
| analytics | { googleAnalyticsId: string } / { googleAnalyticsId: ‘’ } | 配置容器，部分覆盖即可；没有额外 enabled 字段 | { googleAnalyticsId: ‘G-XXXXXXXXXX’ } |
| analytics.googleAnalyticsId | string / ‘’ | 條件生效：有效 ID、正式建置且未命中本機位址略過規則時載入 GA4。空字串或純空白關閉；首尾空白會移除。正規表示式為 ^G-\[A-Z0-9\]+$，前綴及後續字母必須大寫；格式錯誤會在元件解析時拋出錯誤 | ‘G-XXXXXXXXXX’ |

這是 GA4 網頁資料流的 Measurement ID，不是數字屬性 ID、GTM 容器 ID、舊 UA ID 或 API 密鑰。範例只示範格式，正式使用替換為自己的真實值。驗證不要求固定字元數量，也不會聯網驗證 ID 是否屬於有效資料流；不要把「通過正規表示式」理解成「已收到統計資料」。

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

關閉統計可合併：

```ts
analytics: { googleAnalyticsId: '' },
```

合併到現有 `defineThemeConfig({...})`，不要重複建立 analytics。一個 ID 用於整合公共框架的各語言頁面，沒有按語言或頁面分別設定 ID 的欄位。

### 哪些情況下會載入？

| 環境或地址 | 目前主題行為 |
| --- | --- |
| npm run dev | 不輸出統計載入器；但欄位仍先解析，錯誤格式不保證被忽略 |
| 正式環境建置，ID 為空 | 不輸出統計載入器 |
| 正式環境建置，瀏覽 localhost 或其 .localhost 子域 | 載入器提前返回，不初始化主題的統計佇列，也不請求 Google |
| 正式環境建置，瀏覽 127. 開頭地址、0.0.0.0、::1 或 \[::1\] | 同樣跳過；地址比較先轉小寫 |
| 正式環境建置，瀏覽局域網 IP 或遠程預覽網域 | 不因它是「預覽」自動排除；設定了 ID 就會嘗試載入 |
| 正式環境建置，正式網域與有效格式 ID | 初始化一次 gtag 佇列，非同步插入 Google 客戶端 |

主題執行 js 初始化和 config 指令，沒有額外再手動發送一條 page\_view，也沒有添加搜尋詞、播放器操作等自訂事件。重複執行同一載入器有一次性標記，但不會識別你通過其他工具另裝的一套統計；已有手動腳本或 GTM 時，應確認沒有重複安裝。

已有 window.dataLayer 和 window.gtag 會被保留；主題沒有附帶同意管理面板、自動同意設定、代理上報、排除網域列表或自訂事件設定。目前 ID 不通過專用 PUBLIC\_GA\_\* 環境變數自動覆寫；環境控制需由你自己的 site.config 明確處理，不能隨意填一個變數名期待主題讀取。

公共組件對舊自訂介接器缺少 ANALYTICS 分支的情況按未設定處理，這是內部相容最終備援，不是另一個推薦填寫的設定路徑。實際仍只填寫 analytics.googleAnalyticsId。

## aiReadableContent：全域公開補充

型別為可省略的 MachineReadableSupplement 物件，主題預設未設定。省略時仍生成機器閱讀檔案，只是不附加這組額外說明；填寫 {} 也不是關閉導出的開關。

| 完整路徑 | 型別 / 預設值 | 狀態、作用與限制 | 範例值 |
| --- | --- | --- | --- |
| aiReadableContent.notes | string，可省略 / 未設定，輸出為空 | 條件生效：向公開文字加入 Markdown 網站說明；空字串或純空白不輸出該部分。不是文章內文替換，也不是給某個 AI 的私有提示 | ‘本站內容是個人學習筆記，可能持續修訂。’ |
| aiReadableContent.links | { label: string; href: string }\[\]，可省略 / 未設定，輸出空列表 | 條件生效：附加公開連結；陣列整體替換，\[\] 清空；沒有公開條數上限，不自動抓取連結目標內容 | \[{ label: ‘專案主頁’, href: ‘[https://example.com/project/’](https://example.com/project/%E2%80%99) }\] |
| aiReadableContent.links\[\].label | string，必填 / 無 | 條件生效：顯示名稱必須 trim 後非空；生成時將換行折為空格，並轉義反斜線與方括號。不會從目標頁面自動獲取標題 | ‘專案主頁’ |
| aiReadableContent.links\[\].href | string，必填 / 無 | 條件生效：必須非空，按發佈根 URL 解析；解析後僅允許 HTTP(S)，且不能帶用戶名或密碼。非法值會報錯，不驗證目標存在或可瀏覽 | ‘[https://example.com/project/](https://example.com/project/)’ |

notes 和 links 沒有通用字元長度設定；必須遵守對應型別。錯誤型別、空白連結名稱、非網頁協議或帶憑據的連結可能阻止建置。主題不執行補充中的指令，也不呼叫模型生成這些說明。

### Markdown 和相對連結如何處理？

notes 保留 Markdown 文字、格式和程式碼範例；其中解析到的 Markdown 連結、圖片與引用定義的目標會轉成絕對地址，並接受相同的 HTTP(S) 與無憑據驗證。程式碼塊裡的連結範例不作為真正目標改寫。不要把它理解成任意 HTML 的完整驗證器或網頁擷圖服務。

連結解析基準是**網站公開根 URL，包含 Astro base**，不是目前文章 URL，也不是目前語言目錄。例如發佈根是 [https://example.com/project/：](https://example.com/project/%EF%BC%9A)

| 設定中的 href 或 Markdown 目標 | 解析結果 |
| --- | --- |
| zh/blog/ | [https://example.com/project/zh/blog/](https://example.com/project/zh/blog/) |
| /zh/blog/ | [https://example.com/zh/blog/](https://example.com/zh/blog/) |
| [https://docs.example.com/guide/](https://docs.example.com/guide/) | 保持該外部網址 |

所以子路徑部署時，單個 / 開頭會從網域根計算，不自動保留 /project/。這與音樂等組件對根路徑添加 BASE\_URL 的處理不同，不能混用規則。mailto:、tel:、file:、javascript: 等不用於這組附加連結；內文中的正常聯絡連結有自己的導出規則，不代表補充連結也接受相同協議。

### 全域範例

```ts
aiReadableContent: {
  notes: '本站內容是個人學習筆記，可能持續修訂。詳情見[文章列表](zh/blog/)。',
  links: [
    { label: '專案主頁', href: 'https://example.com/project/' },
  ],
},
```

## 按語言覆寫 aiReadableContent

完整前綴為 `i18n.locales.<locale>.aiReadableContent`，同樣是可省略的 MachineReadableSupplement，預設未設定。下面欄位作用與全域欄位一致，差異是未設定時逐欄位繼承全域值：

| 相對欄位 | 型別 / 預設值 | 作用與限制 | 範例值 |
| --- | --- | --- | --- |
| notes | string，可省略 / 繼承全域 notes | 條件生效：該語言公開文字的補充；‘’ 或纯空白明确清空，不回退到另一语言 | ‘中文內容持續更新。’ |
| links | { label: string; href: string }\[\]，可省略 / 繼承全域 links | 條件生效：覆寫整個附加連結陣列，\[\] 明確清空，不與全域列表追加合併 | \[\] |
| links\[\].label | string，必填 / 無 | 有自訂條目時必填；驗證與轉義規則和全域相同 | ‘中文文章’ |
| links\[\].href | string，必填 / 無 | 有自訂條目時必填；解析基準仍是發佈根，不是該語言目錄 | ‘zh/blog/’ |

例如只換中文說明、隱藏中文附加連結：

```ts
i18n: {
  locales: {
    zh: {
      aiReadableContent: {
        notes: '中文内容持续更新。',
        links: [],
      },
    },
  },
},
```

只覆寫 notes 時仍繼承全域 links；只寫 {} 會繼承兩項。undefined 被忽略，不是清空指令。此物件不走 meta.fallback，不從英文或其他回退語言複製補充，詳見[語言字典](https://demo.anglefeint.com/zh-hant/blog/config-languages/#fallback)。

根 llms.txt 始終使用全域補充；語言覆寫用於該語言的索引、合集和單篇 Markdown。因此無效的全域補充不能靠在每種語言中清空來繞過，根索引仍會處理它。

## 補充進入哪些公開產物？

以下路徑以網站發佈根為基準；子路徑部署時加上該發佈前綴。只有實際導出了內容的語言才生成對應語言索引和合集，不因填寫語言補充就憑空建立文章。

| 產物 | 補充位置與內容 |
| --- | --- |
| llms.txt | 根入口；全域 notes 放在語言目錄之前，links 作為額外連結區。沒有可導出內容時仍可包含全域補充 |
| `<locale>/llms.txt` | 語言入口；使用該語言覆寫後的說明與附加連結，按 Articles / Fragments / About 分類連結到已有公開文檔 |
| `<locale>/llms-full.txt` | 該語言的公開全文合集；說明與附加連結在文檔內文集合之前 |
| 文章對應的 index.md 等 Markdown | 原內文之後追加分隔線、網站補充標記和有效說明，不混成文章作者內文的一部分 |
| `<locale>/about/index.md` | About 的公開介紹和聯絡內容，以及目前可達的 AI 靜態文字面板；末尾按相同規則追加補充，不導出整個工具執行設定 |
| `<locale>/fragments/index.md` | 分頁碎片合併後的公開內容，保留穩定 ID 連結；末尾追加補充，不按每一分頁生成重複全文合集 |

單篇 Markdown 的實際路徑由建置 HTML 檔案位置決定，index.html 對應 index.md；自訂 Astro 輸出形式可能不同，不要手動拼造並覆寫生成檔案。導出頁面還會獲得指向 Markdown 和對應語言索引的發現連結。

導出器只處理已標記、可公開索引且 canonical 同來源的文章、About 和 Fragments；預設不把首頁、列表、Decoder 工具表單或評論 iframe 導成文章。內文連結、程式碼、表格等從建置後內容轉換，不會把未呈現的任意設定檔案打包公開。About 的 AI 彈窗是已公開可打開的靜態文字，填寫前同樣按公開資料對待。

search: false 只退出 Pagefind，不退出這些機器閱讀產物。清空 notes/links 不關閉內文導出；沒有 aiReadableContent.enabled、排除某篇、AI 服務地址、模型參數或 API key 欄位。這些檔案提供可讀取的公開材料，不保證任何模型抓取、引用或提高排名。

生成器會保護不屬於自身歷史清單的同名檔案，衝突時報錯；不要在 public 或建置目錄手動放一份相同路徑的 llms.txt 或 Markdown 與之搶占。修正來源設定後重新建置，部署時完整上傳生成產物；建置通過不代表線上已更新或某個模型已讀取。

## 相關設定與目前設定邊界

*   網站公開地址由 site.url、環境覆寫和 Astro 發佈 base 共同影響；根索引標題與描述使用目前網站上下文。網站資訊和部署方式見[發佈教學](https://demo.anglefeint.com/zh-hant/blog/starter-guide-deployment/)，不要在補充文字裡修改網址就期待 canonical 一起變化。
*   語言啟停影響標準頁面生成；關閉不等於自動清除託管平臺舊檔案。補充文字不建立譯文，相關設定見[語言字典](https://demo.anglefeint.com/zh-hant/blog/config-languages/#ai-context)。
*   GA4 只影響統計載入，不控制搜尋、RSS 或機器閱讀；靜態補充也沒有自己的介面按鈕、翻譯文字或瀏覽統計開關。
*   目前 GA4 ID 和所有補充欄位都有消費位置，沒有額外的過期欄位需要填寫。舊介接器缺少統計分支僅按未啟用相容，不是啟用方式。

修改後需要重新建置部署。統計結果仍可能受瀏覽器攔截、網路或統計端設定影響；本機文字生成檢查不能代替線上統計驗收。返回[設定字典總入口](https://demo.anglefeint.com/zh-hant/blog/config-reference/)查其他模組。
