設定字典:GA4 瀏覽統計、AI 閱讀補充說明
統計 ID、正式環境載入條件,以及公開機器閱讀文字中的網站補充。
本頁目錄
第一次發佈可讀部署教學,其中介紹統計 ID 獲取和公開文字用途。設定檔案位置見安裝與網站資訊,其他模組從設定字典總入口進入。
這兩組設定寫在 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 是否屬於有效資料流;不要把「通過正規表示式」理解成「已收到統計資料」。
analytics: {
googleAnalyticsId: 'G-XXXXXXXXXX',
},
關閉統計可合併:
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/’ }] |
| aiReadableContent.links[].label | string,必填 / 無 | 條件生效:顯示名稱必須 trim 後非空;生成時將換行折為空格,並轉義反斜線與方括號。不會從目標頁面自動獲取標題 | ‘專案主頁’ |
| aiReadableContent.links[].href | string,必填 / 無 | 條件生效:必須非空,按發佈根 URL 解析;解析後僅允許 HTTP(S),且不能帶用戶名或密碼。非法值會報錯,不驗證目標存在或可瀏覽 | ‘https://example.com/project/’ |
notes 和 links 沒有通用字元長度設定;必須遵守對應型別。錯誤型別、空白連結名稱、非網頁協議或帶憑據的連結可能阻止建置。主題不執行補充中的指令,也不呼叫模型生成這些說明。
Markdown 和相對連結如何處理?
notes 保留 Markdown 文字、格式和程式碼範例;其中解析到的 Markdown 連結、圖片與引用定義的目標會轉成絕對地址,並接受相同的 HTTP(S) 與無憑據驗證。程式碼塊裡的連結範例不作為真正目標改寫。不要把它理解成任意 HTML 的完整驗證器或網頁擷圖服務。
連結解析基準是網站公開根 URL,包含 Astro base,不是目前文章 URL,也不是目前語言目錄。例如發佈根是 https://example.com/project/:
| 設定中的 href 或 Markdown 目標 | 解析結果 |
|---|---|
| zh/blog/ | https://example.com/project/zh/blog/ |
| /zh/blog/ | https://example.com/zh/blog/ |
| https://docs.example.com/guide/ | 保持該外部網址 |
所以子路徑部署時,單個 / 開頭會從網域根計算,不自動保留 /project/。這與音樂等組件對根路徑添加 BASE_URL 的處理不同,不能混用規則。mailto:、tel:、file:、javascript: 等不用於這組附加連結;內文中的正常聯絡連結有自己的導出規則,不代表補充連結也接受相同協議。
全域範例
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/’ |
例如只換中文說明、隱藏中文附加連結:
i18n: {
locales: {
zh: {
aiReadableContent: {
notes: '中文内容持续更新。',
links: [],
},
},
},
},
只覆寫 notes 時仍繼承全域 links;只寫 {} 會繼承兩項。undefined 被忽略,不是清空指令。此物件不走 meta.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 共同影響;根索引標題與描述使用目前網站上下文。網站資訊和部署方式見發佈教學,不要在補充文字裡修改網址就期待 canonical 一起變化。
- 語言啟停影響標準頁面生成;關閉不等於自動清除託管平臺舊檔案。補充文字不建立譯文,相關設定見語言字典。
- GA4 只影響統計載入,不控制搜尋、RSS 或機器閱讀;靜態補充也沒有自己的介面按鈕、翻譯文字或瀏覽統計開關。
- 目前 GA4 ID 和所有補充欄位都有消費位置,沒有額外的過期欄位需要填寫。舊介接器缺少統計分支僅按未啟用相容,不是啟用方式。
修改後需要重新建置部署。統計結果仍可能受瀏覽器攔截、網路或統計端設定影響;本機文字生成檢查不能代替線上統計驗收。返回設定字典總入口查其他模組。