配置字典: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.<语言>.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 作为额外链接区。没有可导出内容时仍可包含全局补充 |
<语言>/llms.txt |
语言入口;使用该语言覆盖后的说明与附加链接,按 Articles / Fragments / About 分类链接到已有公开文档 |
<语言>/llms-full.txt |
该语言的公开全文合集;说明与附加链接在文档正文集合之前 |
| 文章对应的 index.md 等 Markdown | 原正文之后追加分隔线、站点补充标记和有效说明,不混成文章作者正文的一部分 |
<语言>/about/index.md |
About 的公开介绍和联系内容,以及当前可达的 AI 静态文本面板;末尾按相同规则追加补充,不导出整个工具运行配置 |
<语言>/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 和所有补充字段都有消费位置,没有额外的过期字段需要填写。旧适配器缺少统计分支仅按未启用兼容,不是启用方式。
修改后需要重新构建部署。统计结果仍可能受浏览器拦截、网络或统计端设置影响;本地文本生成检查不能代替线上统计验收。返回配置字典总入口查其他模块。