> ## Documentation Index > Fetch the complete documentation index at: https://blogloom.changlu.cloud/llms.txt > Use this file to discover all available pages before exploring further. # BlogLoom SEO 原理03：Google AdSense 广告接入配置指南 > 从发布商 ID 到自动 / 手动广告位与 ads.txt：Google AdSense 在 BlogLoom 的接入与配置实践。 # 搜索引擎SEO优化调研学习03、Google AdSense 广告接入配置指南 > **本文定位：** 把《搜索引擎SEO优化调研学习02》里分散在 **4.4 广告接入需求与原理分析** 与 **5.3 广告接入（Google AdSense）** 两块内容，抽出来整理成一篇**可独立阅读、可直接照做**的 AdSense 配置指南。 > > 与早期方案相比，本文的操作部分已对齐 **BlogLoom 当前真实实现**：后台是「**总开关 + 四段式表单**」，广告位**直接粘贴 Google 代码**由系统自动识别，**技术位置由系统内部维护**，`ads.txt` 通过「**验证并下载**」按钮生成。 *** # 一、背景引入：流量有了，收益从哪来 ## 1.1、一个真实场景：文章被收录了，然后呢？ 在 02 篇里，我们花了很大力气让 BlogLoom 从「爬虫眼里的空壳」变成「能被收录的博客」：服务端直出、sitemap、robots、canonical、结构化数据…… 文章慢慢被 Google 收录，也来了自然流量。这时候一个很自然的问题出现了： > **流量来了，怎么让它变成收益？** 对于个人技术博客，最常见、门槛最低的答案就是——**Google AdSense**。 ## 1.2、为什么先接 Google AdSense？——四种变现方式对比 广告与变现平台有很多：Google AdSense、国内广告联盟（如百度联盟）、CPS 带货、品牌赞助……为什么第一阶段只选 Google AdSense？ | 选择 | 门槛 | 与博客的匹配度 | 结算 | 结论 | | - | - | - | - | - | | **Google AdSense** | 有网站即可申请，需内容审核 | 与「原创技术博客」高度契合，自动匹配技术/工具类广告 | 满 100 美元电汇，国内可用 | **首选** | | 国内广告联盟 | 多要求备案、流量门槛高 | 个人站一般达不到 | 人民币，门槛不一 | 后续可选 | | CPS / 带货 | 需选品、写推广文 | 会稀释内容调性 | 佣金制 | 不强求 | | 品牌赞助 | 需议价、接洽 | 依赖流量 | 一单一议 | 有流量后再说 | **核心判断：** AdSense 是「接入成本最低、对内容破坏最小、又能覆盖全球技术流量」的起步方案。先把 AdSense 跑通，就等于验证了「**内容 → 流量 → 收益**」这条路是通的。 ## 1.3、AdSense 与 SEO 的正向循环 很多人以为「做 SEO」和「接广告」是两件事，其实 AdSense 审核恰恰依赖一阶段 SEO 的产出。它们是一个正向循环： ```plain theme={null} SEO 改造（可抓取 + sitemap + 隐私政策 + 清晰结构） ↓ 通过 Search Console 被收录、有自然流量 ↓ AdSense 申请时「看起来像认真运营的站」 ↓ 过审 → 投放 → 收益 ``` **重点：** AdSense 不是「申请了就批」。它有一套**内容与合规红线**（见 3.5），其中很大一部分（隐私政策、可抓取、sitemap、站点结构清晰）**正是 02 篇已经做完的事**。换句话说：**SEO 改造做扎实，AdSense 过审会顺很多。** ## 1.4、本文范围与阅读指引 > **范围说明：** 广告属于变现阶段，不在「收录最小闭环」里。但 BlogLoom 已经在代码层把 AdSense 的**配置、装配、注入、ads.txt** 全部落地，所以本文按「**原理 → 需求 → 配置规则 → 代码 → 实操 → 验证**」的顺序完整讲清。 阅读顺序建议： | 章节 | 内容 | 适合谁 | | - | - | - | | 二、核心概念讲解 | 加载器 / 广告单元 / 发布商 ID / 投放方式 / ads.txt | 第一次接触 AdSense 的人 | | 三、核心功能需求分析调研 | 需求清单、布局、合规、收益、FAQ | 产品/需求梳理 | | 四、功能需求与 UI 配置规则 | 后台四段式表单与全部校验规则 | 前端/测试/验收 | | 五、核心代码设计实现 | 数据模型、装配、注入、ads.txt | 后端/全栈 | | 六、实战配置步骤 | 申请、建单元、填后台、上线 | 站长本人 | | 七、验证测试 | 浏览器 / curl / 单元测试 | 测试/上线前 | *** # 二、核心概念讲解：先搞懂这些再动手 写代码、配后台之前，先把概念理清，否则很容易出现「**代码贴了，广告却不显示**」的情况。 ## 2.1、三样东西：加载器、广告单元、自动广告 AdSense 在页面层面的构成，其实只有三样东西： | 概念 | 英文 | 作用 | 放在哪 | | - | - | - | - | | **AdSense 代码**（加载器） | AdSense code / adsbygoogle.js | 加载 AdSense SDK，是所有广告的基础脚本 | 每个页面的 `` | | **广告单元** | Ad unit | 一个具体的广告位，带唯一 `data-ad-slot` | 页面正文里，用 `` 占位 | | **自动广告** | Auto ads | 由 Google 自动决定在页面哪里插广告 | 只要加载器在，Google 自己插 | 官方说明：**「要把 AdSense 代码放在每个页面的 `` 和 `` 之间」**，才能覆盖全站、让 Auto ads 生效（[About the AdSense code](https://support.google.com/adsense/answer/9274634)）。 **关键更新：** 官方已说明 **Auto ads 现在可以通过任意 AdSense 广告单元代码生效**，不再强制要求单独粘贴 Auto ads 代码——**只放一个「广告单元」代码，也能吃到 Auto ads 的自动投放**。 **① 加载器代码形态：** ```html theme={null} ``` **② 广告单元代码形态：** ```html theme={null} ``` 参数含义（官方 [自适应广告代码参数](https://support.google.com/adsense/answer/9183460)）： | 参数 | 含义 | 取值 | | - | - | - | | `data-ad-client` | 发布商 ID | `ca-pub-…` | | `data-ad-slot` | 广告单元 ID | 数字串 | | `data-ad-format` | 大体形状（桌面） | `auto` / `rectangle` / `horizontal` / `vertical` | | `data-ad-layout` | 内容内嵌布局 | 如 `in-article` | | `data-full-width-responsive` | 移动端是否全宽展开 | `true`（官方推荐）/ `false` | **重点：** * **加载器只需一次**（``），**每出现一个 `` 广告位，就要紧跟一次 `push({})`**；少 push 不显示，多 push 会报错。 * 自适应广告的父容器要**有稳定宽度**；父容器为 `width:auto` 或运行时才算宽，可能出现移动端布局异常。 ## 2.2、两级 ID：发布商 ID 与广告位 ID 这是最容易搞混、也最该先搞清的一点。AdSense 里的标识分**两级**： | 标识 | 数量 | 是什么 | 出现在哪 | | - | - | - | - | | **发布商 ID**（`ca-pub-XXXX`） | **全站唯一** | 整个 AdSense 账号的 ID | 加载器脚本、每个广告位的 `data-ad-client` | | **广告位 ID**（`data-ad-slot`） | **可以有多个** | 一个「广告单元」一个 ID | 每个 `` 广告位 | **「是否有多个」要分开看：** | 参数 | 单/多 | 说明 | | - | - | - | | `client`（发布商 ID） | **单** | 一个账号一个，全站所有广告位共用同一个 | | `slots[].slot`（广告位 ID） | **多** | 顶部、底部各放一个 → 建 2 个「广告单元」 → 拿 2 个 slot ID | | `adsTxt` | 单文件、多行 | 只接 Google 通常 1 行；接多家联盟才多行 | **结论：** * **发布商 ID 永远只配一个**，它是总开关。 * **广告位想放几个就建几个**，数量完全由你定。 * 多个 slot 不是「同一广告单元的多个参数」，而是**互相独立的广告单元**（各自独立报表、独立样式）。 > **BlogLoom 的设计取舍：** 后台只维护**一个配置项** `adsense`（一组 JSON），发布商 ID、广告位列表、ads.txt 全在这一个 JSON 里——**不新增表、不新增字段**。 ## 2.3、投放方式：按网站、按广告单元、混合投放 在 AdSense 里，「按网站」和「按广告单元」**不是二选一**，它们可以独立使用，也可以同时使用： | 方式 | AdSense 后台入口 | 位置由谁决定 | BlogLoom 对应配置 | | - | - | - | - | | **按网站（自动广告）** | Ads → By site | Google 根据页面自动选择 | `autoAds=true`，可以不配置 `slots` | | **按广告单元（手动广告）** | Ads → By ad unit | BlogLoom 根据 `position` 精确渲染 | `autoAds=false`，配置一个或多个 `slots` | | **混合投放** | 两处都配置 | Google 自动补位 + BlogLoom 手动位 | `autoAds=true`，同时配置多个 `slots` | | `autoAds` | 是否存在已启用 slot | BlogLoom 是否加载全局脚本 | 实际投放方式 | | - | - | - | - | | `false` | 否 | 否 | 不投放 | | `true` | 否 | 是 | 仅自动广告 | | `false` | 是 | 是 | 仅手动广告单元 | | `true` | 是 | 是 | 自动广告 + 手动广告单元 | > **关键边界：** `adsbygoogle.js` 是自动广告和手动广告**共用的加载器**，脚本 URL 本身**没有** `autoAds=true/false` 参数。`autoAds` 表示 BlogLoom 的投放意图，**Google 是否真正自动插入广告，最终仍由 AdSense 后台「按网站」开关决定**。 因此需要同步完成以下操作： 1. 选择「仅自动广告」或「混合投放」时，需在 AdSense 后台 `Ads → By site` 中**开启**该站点的自动广告。 2. 选择「仅手动广告单元」时，需在 AdSense 后台**关闭**该站点的自动广告；否则即使 BlogLoom 配置 `autoAds=false`，Google 仍可能通过同一加载器自动插入广告。 3. `slots` 可以为空，也可以配置多个；每个 slot 对应一个独立广告单元。 ## 2.4、ads.txt：站点级「授权售卖」声明 `ads.txt` 是 IAB Tech Lab 规范（[官方说明](https://developers.google.com/adsense/platforms/transparent/ads-txt)）：**非强制，但不放会损失部分预算**——很多广告主只对「已验证 ads.txt」的广告请求出价。文件放**域名根目录**，只接 Google 时内容一行： ```plain theme={null} google.com, pub-0000000000000000, DIRECT, f08c47fec0942fa0 ``` > `pub-0000000000000000` 是发布商 ID（**去掉 `ca-` 前缀**）；`f08c47fec0942fa0` 是 Google 固定认证标识。这与本项目 `robots/sitemap/rss` 的站点级文件机制同构（见 02 篇 5.1.3）。 ## 2.5、站点验证：AdSense 代码 或 meta 标签 | 方式 | 做法 | 适用 | | - | - | - | | **AdSense 代码** | 把加载器代码放进首页 `` | 首页就要展示广告的常规站 | | **meta 标签** | 在首页 `` 放一段验证 meta | **不想在首页放广告**时（官方新增） | 官方（[站点管理改进](https://support.google.com/adsense/answer/13996652)）：新增 `meta tag` 验证，**「不想在首页展示广告时，可用 meta 标签替代 AdSense 代码片段验证」**。 BlogLoom 首页是 SPA，已有 `SpaIndexController` 向 SPA 入口注入 meta 的能力，可直接沿用 meta 标签方案： ```html theme={null} ``` ## 2.6、关键概念对照表 | 概念 | 一句话记忆 | BlogLoom 落点 | | - | - | - | | 加载器 `client` | 全站总开关，Auto ads 靠它 | `` 一份 | | 广告位 `slot` | 一个手动广告单元 | `` 里一段 `` | | `autoAds` | 投放意图开关 | 后台第 2 段配置 | | `ads.txt` | 授权售卖声明 | `/ads.txt` | | `position` | 模板里的位置标记 | 系统内部维护，用户无感 | *** # 三、核心功能需求分析调研 本章回答「**要做什么、为什么这么做、有哪些约束**」，是后面「配置规则」与「代码实现」的出发点。 ## 3.1、需求总览（功能点清单） | 编号 | 功能点 | 说明 | 优先级 | | - | - | - | - | | A1 | 广告总开关 | 一键启停全站广告，配置保留 | P0 | | A2 | 发布商 ID 配置 | 全站唯一 `ca-pub-…` | P0 | | A3 | 自动广告开关 | 控制「按网站」投放意图 | P0 | | A4 | 手动广告位配置 | 粘贴 Google 代码，自动识别 slot | P0 | | A5 | 广告位启停 | 单个广告位可单独开关 | P0 | | A6 | SSR 文章页注入 | 加载器 + 手动广告位直出 | P0 | | A7 | SPA 页面注入 | 首页/列表加载器 + 路由切换 push | P1 | | A8 | ads.txt 生成 | 自动生成 / 自定义 + 验证并下载 | P0 | | A9 | 站点验证 meta | 首页注入验证 meta（方案 B） | P1 | | A10 | 配置解析兜底 | 配置损坏时不影响页面 | P0 | ## 3.2、后台如何承载需求：为什么是「一个 JSON + 一个开关」 需求方最容易想到的是「发布商 ID、自动广告、ads.txt、广告位」拆成四个独立配置项。但这样会带来一连串问题：**数据库要加字段、接口要加参数、增删广告位要改代码**。 于是 BlogLoom 选择**单一配置项**方案： | 配置键（nameEn） | 中文名 | 类型 | 说明 | | - | - | - | - | | `adsense` | AdSense 广告配置 | JSON（字符串） | 后台唯一入口；发布商 ID、自动广告、ads.txt、广告位列表全在这一个 JSON 里 | ```json theme={null} { "version": 1, "enabled": true, "client": "ca-pub-1234567890123456", "autoAds": true, "adsTxt": "", "slots": [ { "name": "", "slot": "1111111111", "position": "articleTop", "enabled": true, "format": "auto", "layout": "", "fullWidth": null, "alignment": "center" }, { "name": "", "slot": "2222222222", "position": "articleBottom", "enabled": true, "format": "auto", "layout": "", "fullWidth": null, "alignment": "center" } ] } ``` **设计理由：** 后台只维护一个 JSON，前端表单本质是「一组表单 + 一段校验」，后端只当字符串存取、解析时做兜底；新增/删除位置、临时关广告、改发布商 ID 都只动这一处，**不新增表、不新增字段、不改代码**。 ## 3.3、广告位规划与布局原则 广告放哪，直接决定「体验」和「收益」。参考眼动 F 型浏览路径，**放在读者自然经过的阅读动线上**，比「多塞几个格子」有效得多。 | 位置 | 说明 | BlogLoom 落点 | 建议 | | - | - | - | - | | **首屏之下** | 所有人进门都会经过 | 文章标题后 / 正文前 | 响应式横幅，控制高度，**别让首屏只有广告没正文** | | **文内第一条** | 第 2\~3 段之后，读者已确认「值得读」 | 正文中部 | CTR 通常最高；二阶段做 | | **正文结束处** | 读者处于「接下来看什么」的过渡期 | 正文末尾、相关推荐前 | 矩形 / 信息流样式 | | **桌面侧栏** | 宽屏才有，可 sticky | 文章页左右栏 | 仅桌面；移动端隐藏 | | **页脚 / 侧栏最底** | 长期 CTR 极低还伤体验 | — | **果断砍掉** | **布局原则：** 1. **数量克制：** 3~~4 个高质量位置，通常优于 6~~7 个鸡肋位。 2. **预留尺寸防 CLS：** 广告容器给 `min-height` 或 `aspect-ratio`，避免加载后正文乱跳。 3. **融入而非伪装：** 配色接近站点主题可以；**绝不能**做成「下载按钮」「播放键」或伪装成正文（见 3.5）。 4. **移动端优先：** 用自适应单元（`data-full-width-responsive="true"`），少用手动固定大尺寸撑爆首屏。 ## 3.4、广告位与页面的对应关系 | 页面 | 渲染方式 | 适合的广告位 | 接入方式 | | - | - | - | - | | 文章详情页 `/blog/{id}` | SSR 直出 | `articleTop` / `articleBottom` / `articleSidebarToc`（`articleInArticle` 预留） | 后端模板输出 `` | | 首页 / 列表 / 归档 | Vue SPA | `listTop`（预留） | 前端注入 + 路由 push | | 后台 `/cms`、`/admin` | SPA | **不投** | 后台不对外开放，无需广告 | **核心场景是文章页**：它既是收录主体，也是读者停留最久的地方；SPA 页广告属于锦上添花。 > **现状说明：** 目前实际渲染的位置为 `articleTop`、`articleBottom`（正文内），以及桌面端右栏「本文目录」下方的 `articleSidebarToc`（SSR 与 SPA 均已接入）；`articleInArticle`、`listTop` 已在**校验白名单**中预留，属于进阶项，一阶段可先不做。 ## 3.5、合规与审核要点（红线） AdSense 审核的本质是判断「**你是不是在做对用户有用的网站**」。 **① 申请前的站点条件（与 SEO 改造强相关）：** | 要求 | BlogLoom 现状 | 对应 | | - | - | - | | 内容可抓取（非空壳） | 已完成服务端直出 | 02 篇 5.1.1.2 | | 有 sitemap 并提交 Search Console | 已完成 | 02 篇 5.1.3.2 | | 有隐私政策页（含 Cookie / 第三方说明） | **需确认/补齐** | 新增 | | 有关于 / 联系页面 | 站点已有 About | 现有 | | 全站 HTTPS + 自有顶级域名 | 已满足（changlu.cloud） | 现有 | | 导航清晰、无死链、移动端可用 | 基本满足 | 现有 | > **注意：** 隐私政策页是审核里最容易漏的一项，需写明：使用了 Cookie、接入了 Google AdSense 等第三方、第三方可能基于用户兴趣投放广告。 **② 广告实现红线（官方 [广告投放政策](https://support.google.com/adsense/answer/1346295)）：** | 红线 | 说明 | 对 BlogLoom 的约束 | | - | - | - | | 诱导点击 | 禁止「点广告支持本站」等文案或布局 | 广告旁不放诱导性文字/箭头 | | 伪装成内容 | 禁止做成导航、下载按钮、正文样式 | 广告位有清晰边界与留白 | | 误导性标题 | 禁止用「资源」「有用链接」等标题盖在广告上 | 广告上方不放大标题 | | 未经请求的自动刷新 | 禁止定时器自动刷新广告「刷曝光」 | SPA 只允许「用户切路由后 push 新广告位」 | | 图片与广告对齐 | 禁止让站内图片像广告配图 | 广告与正文图片保持视觉区隔 | | 放在登录墙后 | Google 无法评估的内容不投放 | 私密/密码文章页**不投广告**（与 sitemap 排除一致） | **③ 内容质量（决定能不能过审）：** * **原创、垂直、有信息量**：同一细分领域 8\~15 篇能解决具体问题的原创长文，比「50 篇模板短文」更稳。 * **不是机翻/洗稿**：多平台搬运、机翻当原创，属于高危重复内容。 * **有稳定更新节奏**：几周内持续更新，比「同一天批量发完」更像认真运营。 * **被拒后**：读懂拒信关键词 → 做**可见的整改**（补隐私政策、删违规、修 404、改导航）→ **等 7\~14 天**再申请，**不要连续刷申请**。 ## 3.6、收益与指标：看什么、怎么算 | 指标 | 全称 | 含义 | 用途 | | - | - | - | - | | **Page RPM** | 每千次网页浏览收益 | 1000 次页面浏览能赚多少 | 衡量页面整体变现效率 | | **Impressions RPM** | 每千次广告展示收益 | 1000 次广告展示能赚多少 | 衡量广告位本身质量 | | **CTR** | 点击率 | 点击 ÷ 展示 | 判断位置/样式是否「被看到」 | | **CPC** | 每次点击成本 | 广告主为一次点击付的钱 | 受内容主题（技术类偏高）影响 | **经验参考（非承诺）：** 内容站 CTR 常见 1\~3%，长期低于 0.5% 通常意味着位置或匹配有问题；RPM 波动大，**看周趋势而非单日**。 **结算门槛：** 账户余额累计满 **100 美元**才触发支付；需完成身份验证（PIN 码）与收款方式（国内电汇需 SWIFT/BIC）。 > **重要：广告费的主要变量不是「广告位数量」，而是「内容主题 × 流量质量 × 页面浏览深度」。** 技术博客 CPC 通常不低，把性能与收录做扎实、让文章被更多人看到，比多塞几个广告位更划算。 ## 3.7、常见问题排查（广告不显示） | 现象 | 可能原因 | 排查/解决 | | - | - | - | | 源码里有 ``，但页面空白 | 加载器没注入成功 / 顺序不对 | 确认 `` 有 `adsbygoogle.js`；加载器必须在 `` 之前 | | 有加载器，但广告不出现 | 账号/站点还在审核中 | Sites 状态是否 Ready；审核通过前不投放 | | 只显示一次，切路由后消失 | SPA 路由切换后没重新 push | 见 5.6 的 `pushAdsense`；确认是「新的 ``」 | | 控制台报 `All ins elements already have ads` | 同一 `` 被 push 多次 | 每个元素只 push 一次；代码已用 `data-pushed` 去重 | | 控制台报 `No slot size` | 父容器宽度为 0 或未定义 | 给广告容器固定/最小宽度 | | 移动端撑破布局 | 自适应父容器宽度不稳 | 用 `data-full-width-responsive="true"` + 容器 `width:100%` | | 本机看到广告、线上看不到 | 广告拦截插件 / 地区无库存 | 换无插件浏览器、清缓存；部分地区库存本就少 | | ads.txt 一直 Not found | 路径/内容/缓存问题 | `curl` 确认根目录可访问；内容格式一行；点 Check for updates | | 被拒：「内容不足 / 低价值」 | 篇数或质量不够 | 补垂直原创长文、清理模板文，7\~14 天后再申 | > **调试：** 浏览器 **Network** 过滤 `adsbygoogle` 看 SDK 是否加载；**Console** 看 `push()` 报错。广告竞价有延迟（通常几秒内），刚打开空白属正常。 *** # 四、功能需求与 UI 配置规则 本章是**开发与验收的统一口径**：把「后台长什么样、每个字段什么规则、开关怎么组合、粘贴代码怎么识别」写成明确规则。 ## 4.1、配置总模型 后台配置最终落成一份 JSON，字段定义如下： | 字段 | 类型 | 默认 | 说明 | | - | - | - | - | | `version` | int | 1 | 配置版本号（当前保留，便于后续兼容） | | `enabled` | boolean | `false` | **总开关**；关闭后前台不加载、不渲染，配置保留 | | `client` | string | `""` | 发布商 ID，格式 `ca-pub-数字`，**全站唯一** | | `autoAds` | boolean | `false` | 自动广告投放意图；需与 AdSense 后台「按网站」一致 | | `adsTxt` | string | `""` | 自定义 ads.txt 内容；留空则按 `client` 自动生成 | | `slots` | array | `[]` | 广告位列表，每项对应一个手动广告单元 | 广告位对象 `AdSlot`： | 字段 | 类型 | 说明 | | - | - | - | | `name` | string | 备注名（可选，便于识别） | | `slot` | string | 广告位 ID，**纯数字**，来自 Google 代码 `data-ad-slot` | | `position` | string | 技术位置，**系统内部维护**，用户不直接编辑 | | `enabled` | boolean | 单个广告位启停 | | `format` | string | `auto` / `fluid` / `rectangle` / `horizontal` / `vertical`，默认 `auto` | | `layout` | string | `data-ad-layout`，如 `in-article` | | `fullWidth` | boolean | `data-full-width-responsive`，可空 | | `alignment` | string | `left` / `center` / `right`，默认 `center` | ## 4.2、后台四段式表单（UI 结构） 后台页面：**SEO优化 → 广告平台关联**，组件 `AdvertisingPlatform.vue`。整体由「一个总开关 + 四个编号区块」组成： ```plain theme={null} ┌───────────────────────────────────────────────────────────────┐ │ 广告平台关联 [保存配置] │ ├───────────────────────────────────────────────────────────────┤ │ 启用 AdSense [开关] │ ← 总开关 │ │ │ ① 发布商配置 │ │ 发布商 ID [ ca-pub-1234567890123456 ] │ │ │ │ ② 自动广告 │ │ 开启自动广告 [开关]（总开关关闭时禁用） │ │ │ │ ③ ads.txt 配置 [验证并下载] │ │ ads.txt 内容 [ 文本域，可留空自动生成 ] │ │ │ │ ④ 广告位配置 [新增广告位] │ │ ┌ 广告位 1 [启用开关] [删除] ─────────────────────────┐ │ │ │ 投放位置 [ 下拉选择：文章详情·标题下方 ▾ ] │ │ │ │ Google 代码 [ 粘贴 Google 广告单元代码 ] │ │ │ │ （失焦自动解析）已识别：slot=… format=… layout=… │ │ │ └──────────────────────────────────────────────────────┘ │ │ 新增广告位会按顺序自动分配默认位置，可在广告位内改选。 │ └───────────────────────────────────────────────────────────────┘ ``` **四段与需求映射：** | 区块 | 标题 | 承载字段 | 需求编号 | | - | - | - | - | | 总开关 | 启用 AdSense | `enabled` | A1 | | ① | 发布商配置 | `client` | A2 | | ② | 自动广告 | `autoAds` | A3 | | ③ | ads.txt 配置 | `adsTxt` + 验证并下载 | A8 | | ④ | 广告位配置 | `slots[]` | A4 / A5 | ## 4.3、字段与规则明细（逐字段） | 字段 | 必填 | 前端规则 | 后端规则 | 提示文案 | | - | - | - | - | - | | `client` | 启用广告时必填 | 正则 `^ca-pub-\d+$` | 正则 `^ca-pub-\d+$`，空串放行 | 「发布商 ID 格式应为 ca-pub-数字」 | | `autoAds` | 否 | 总开关关闭时禁用 | 总开关为 `true` 且 `autoAds=true` 时要求 `client` 非空 | — | | `adsTxt` | 否 | 无 | 无 | 留空自动生成；填写后原样输出 | | `slots[].slot` | 启用时必填 | 正则 `^\d+$` | 正则 `^\d+$` | 「slot 必须为数字」 | | `slots[].position` | 是 | 下拉选择（新增时自动分配默认值），不可重复 | 必须在白名单内，不可重复 | 「请为每个广告位选择位置」/「广告位置不能重复」 | | `slots[].format` | 否 | 默认 `auto` | 白名单：`auto/fluid/autorelaxed/rectangle/horizontal/vertical` | 「不支持的广告格式」 | | `slots[].alignment` | 否 | 默认 `center` | 白名单：`left/center/right` | 「不支持的对齐方式」 | **位置白名单（后端单一数据源，经 `GET /admin/seo/adsense/positions` 下发）：** | position | 中文名 | 渲染点 | 适合广告 | | - | - | - | - | | `articleTop` | 文章详情·标题下方 | 文章头之后、正文前 | 展示广告（横幅） | | `articleInArticle` | 文章详情·正文内嵌 | 正文段落之间（进阶，暂未渲染） | 文章内嵌 | | `articleBottom` | 文章详情·正文结束后 | 正文末尾、标签前 | 展示 / 多重广告 | | `articleSidebarToc` | 文章详情·右侧目录下方 | 右栏「本文目录」下方（桌面端） | **纵向广告** | | `listTop` | 列表页·顶部 | 列表页顶部（预留） | 信息流 | **保存前置校验（前端 `validate`，与后端一致）：** 1. `client` 非空时必须匹配 `^ca-pub-\d+$`； 2. 若「启用 + （自动广告 或 至少一个启用的广告位）」，则 `client` 不能为空 → 否则提示「启用自动广告或手动广告位前请填写发布商 ID」； 3. 每个广告位必须有 `position`； 4. `position` 不能重复； 5. 启用的广告位必须能成功解析出 `slot`。 > **重点：** 前端校验与后端 `AdsenseConfigController.validate()` **规则同构**，后端做最终兜底——即使绕过前端，非法配置也会被拒绝，不会写库。 ## 4.4、开关组合行为矩阵 这是配置逻辑的核心，验收时可直接对照： | `enabled` | `client` | `autoAds` | 是否存在启用 slot | `` 加载器 | `` 手动位 | `/ads.txt` | | - | - | - | - | - | - | - | | `false` | 任意 | 任意 | 任意 | **不注入** | **不渲染** | **空** | | `true` | 空 | 任意 | 任意 | 不注入 | 不渲染 | 空（保存时通常已被校验拦截） | | `true` | 非空 | `true` | 否 | **注入** | 不渲染 | 自动生成一行 | | `true` | 非空 | `true` | 是 | **注入** | **渲染** | 自动生成一行 | | `true` | 非空 | `false` | 是 | **注入** | **渲染** | 自动生成一行 | | `true` | 非空 | `false` | 否 | 不注入 | 不渲染 | 自动生成一行 | **加载器注入条件（三条件同时满足）：** ```plain theme={null} enabled != false 并且 client 非空 并且（autoAds == true 或 至少存在一个 enabled != false 且 slot 非空的广告位） ``` > **注意 `enabled` 的空值语义：** 后端多处以 `Boolean.FALSE.equals(enabled)` 判断——即 `enabled == null` 视为**启用**，只有显式 `false` 才关闭。前端初始值固定为 `false`，避免误开。 ## 4.5、广告位代码解析规则（粘贴即识别） 用户在「④ 广告位配置」只需**粘贴 Google 提供的完整广告单元代码**，系统在 `blur`（失焦）时自动解析，**不会原样执行粘贴的脚本**。 **解析流程（`parseSlotCode`）：** ```plain theme={null} 粘贴代码 ↓ DOMParser 解析为 DOM 查找 ├─ 找不到 → 提示「未识别到 广告单元」 ↓ 提取 client： ├─ 优先取 ins 的 data-ad-client └─ 找不到 → 从 ``` **② 文章模板按位置渲染广告位**（`templates/seo/blog.html`，取不到 slot 就不渲染）： ```html theme={null}
``` `articleBottom` 同构。**注意：** `th:if` 里先判断 `client` 非空 **且** 该位置有 slot，二者缺一不渲染——这正是「**取不到就不输出**」的兜底。 **右栏位（`articleSidebarToc`）** 渲染在 `seo/blog.html` 的右侧目录 `