全文约 2,170 字，读完约 7 分钟
折腾博客赚钱的站长，十有八九都踩过同一个坑：去百度联盟或 360联盟后台拿到一段广告代码，兴冲冲贴进文章里，结果——页面直接白了。原因不复杂：联盟代码里大量用 document.write，而现代页面加载完之后再执行 document.write，浏览器会直接把整个文档清空重写。
另一个坑是位置。我的博客用的是卡尼奶风格主题（knn-theme），首页是卡片流，主题把卡片拼成字符串直接输出，没有标准的 WP 循环钩子可以让我把广告插进卡片之间。市面上的广告插件要么只支持段落插入，要么在首页根本无处下手。
所以我干脆自己写了一个：KNN 广告位管理（knn-ad-manager），专门为接入百度联盟 / 360联盟这类代码而生，目前已经在这个站上跑着。
一、这个插件能做什么
一句话：后台新建广告位 → 整段粘贴联盟代码 → 选投放位置 → 保存，前台自动渲染，带「广告」合规标识、懒加载、设备/分类定向和展示统计。
八种投放位置
| 位置 | 说明 | 适合 |
|---|---|---|
| 页头横幅 | wp_body_open 钩子，页面最顶部 |
横幅 / 通栏 |
| 文章内容前 | 正文最上方 | 高曝光 |
| 文章第 N 段后 | 自己指定段落号，超过段数自动追加到文末 | 信息流原生感最强 |
| 文章正文后 | 文末 | 低打扰，转化位 |
| 信息流 | 首页 / 搜索 / 分类页卡片之间，可设「每 N 张卡片插一次」 | 列表页主力位 |
| 页脚横幅 | wp_footer 钩子 |
横幅 / 备案区上方 |
| 短代码 | |
灵活补位 |
| 小工具 | 拖到任意侧边栏 / 页脚小工具区 | 侧边栏常驻 |
三种平台
百度联盟、360联盟（点睛营销）、自定义代码。平台只是标记，代码框接受任意 HTML / JS，所以接其他联盟也完全没问题。后台编辑器里还内置了两个联盟的取码提示，照着复制粘贴即可。
定向与体验
- 设备定向：全部 / 仅 PC / 仅移动端。信息流广告在手机上体验差的话，可以只给桌面端投。
- 分类定向：可以只投某些分类的文章，也可以排除某些分类（排除优先）。
- 懒加载：广告进入视口才执行联盟代码（IntersectionObserver，提前 300px 预触发），首屏速度几乎不受影响。
- 展示统计：每个广告位独立计数，按「IP + 广告位」做 60 秒去重，避免刷新一次涨一百的虚假数据。
- 全局总开关：设置页一键停投全站所有广告，排查问题或临时下线不用挨个删。
合规标识
按《互联网广告管理办法》要求，广告必须具有可识别性。插件会在每个广告位左上角渲染「广告」角标，文案可在设置页自定义。
二、技术上解决了什么（感兴趣的看）
这部分写给同样踩坑的开发者。
1. 信息流广告为什么必须先包 <template>
克隆出来的 <script> 一旦 append 进 DOM 就会立即执行，而此时文档早已解析完毕——document.write 会清空整页。所以信息流位置的代码一律先写进 <template>，克隆时再把内容挪进容器并按顺序重建执行，期间接管 document.write / writeln，把输出捕获后 flush 回广告容器（也就是 writeCapture 的思路）。src 脚本还会等 onload 再继续，保证串行语义。
2. 不写死卡片类名
主题的卡片类名是 .knn-card-item，不是常见的 .card。注入逻辑用 :scope > * 逐个取子节点过滤，主题升级改了类名也不会失效。AJAX 翻页追加新卡片时，MutationObserver 防抖 60ms 重排，已激活的广告节点只移动不重建，不会重复计数。
3. 懒加载与统计怎么配合
广告渲染时包一层 <template> 占位，IntersectionObserver 监到进入视口才执行代码，执行成功那一刻上报一次展示。同一个 IP 60 秒内重复触发会被 transient 拦掉。隐藏模板容器里的本体被明确排除在观察之外，不会误激活。
4. 零广告位时零开销
全站没有任何广告位时，前台不输出任何标记、不加载任何 JS/CSS——插件对性能的影响以「有广告」为前提。
三、使用教程
- 后台左侧菜单找到「广告位」，点「新建广告位」；
- 平台选百度联盟或 360联盟，把联盟后台拿到的整段代码原样粘贴进代码框（不要改动）；
- 选投放位置。推荐起步组合：「文章第 2 段后」+「信息流每 4 张卡片」；
- 按需设置设备、分类定向和懒加载，发布；
- 回到「广告位」列表就能看到每个位子的展示次数。
注意：如果你的站点开了强缓存（比如 WP Rocket），新增广告位后记得清一下缓存再看前台。
四、写在最后
这个插件目前在我的站上稳定运行，代码结构很简单——一个 PHP 主文件 + 前后台各一份 CSS/JS，没有第三方依赖，卸载时会清理掉自己留下的所有数据。
后面计划加的是：多广告位轮换（同位置随机选一个展示）、点击统计、以及接入文章内容的智能段落密度检测。如果你在接入联盟广告时也踩过 document.write 的坑，欢迎留言交流你的解法。
