Highlight.io WordPress 插件接入指南：为 WordPress 站点启用会话回放、错误监控与日志采集-育师

可观测性
后端

【免费下载链接】highlight

highlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.

项目地址：https://gitcode.com/gh_mirrors/hi/highlight

点击查看免费下载

本篇技术指南以 Highlight.io 开源全栈可观测平台（错误监控、会话回放、日志、分布式追踪）的官方 WordPress 集成为核心，讲解如何通过官方插件Highlight.io Session Recording为 WordPress 站点快速接入前端监控能力：安装、配置、工作原理、最佳实践与故障排查，并辅以仓库内插件源码（highlight-io.php）与本地测试环境（e2e/wordpress）的源码级佐证。读完本文，你将掌握从零接入到深度配置、再到自托管与本地联调的全套实战方案。

插件能做什么

Highlight.io WordPress 插件是一枚标准的 WordPress 插件，它把 Highlight 的前端 SDK（浏览器端highlight-run）自动注入到站点前台页面，从而实现：

会话回放（Session Recording）：捕获访客在 WordPress 站点上的真实交互过程，以可回放的视频形式在 Highlight 控制台中还原用户操作轨迹；
错误监控（Error Monitoring）：自动检测并记录前端 JavaScript 错误，附带完整堆栈与上下文信息，便于定位问题；
网络请求录制（Network Recording）：可选开启，记录页面发出的网络请求与响应，用于排查 API 调用与第三方集成问题；
控制台日志录制（Console Log Recording）：捕获并回看浏览器 console 输出，辅助快速定位问题；
性能数据采集：随前端 SDK 一并上报页面性能指标（插件描述中明确列出的能力之一）。

这些能力统一由 Highlight 的前端 SDK 提供，插件的作用是"免写代码"地把 SDK 以正确配置加载到 WordPress 前台。

安装步骤

从 WordPress 插件市场安装

登录 WordPress 后台管理面板；
进入"插件（Plugins）"→"安装插件（Add New）"；
在搜索框中输入Highlight.io；
在搜索结果中找到Highlight.io Session Recording，点击"现在安装（Install Now）"；
安装完成后点击"启用（Activate）"激活插件；
进入 Highlight.io 设置页面完成配置。

从仓库手动安装（开发/自托管场景）

插件源码位于仓库 sdk/highlight-wordpress/highlight-io 目录，包含三个文件：

highlight-io.php—— 插件主文件，注册设置页、字段校验与前台脚本注入逻辑；
readme.txt—— WordPress 插件目录标准说明文件（含依赖、隐私声明、FAQ 与打包说明）；
uninstall.php—— 卸载时清理highlight_wp_options配置项。

将highlight-io目录整体放入 WordPress 的wp-content/plugins/目录，然后在后台"插件"页激活即可。注意：前台实际加载的highlight.js是构建产物，如需手动安装请先按下文"构建与打包"生成该文件。

插件兼容性要求（依据 readme.txt）：WordPress 最低 5.0、最高测试至 6.7，要求 PHP 7.2 及以上，遵循 GPLv2 协议。

配置详解

安装并激活插件后，在 WordPress 后台进入设置（Settings）→ Highlight.io即可打开配置页。页面由插件源码中的page_init()方法注册（见 highlight-io.php），所有配置项保存于highlight_wp_options选项数组中，并在提交时经sanitize()方法做安全校验。

必填项：Project ID

Project ID是唯一必填配置。它告诉 Highlight 数据应发送到哪个项目，可在 app.highlight.io/setup 的项目设置中找到。在源码中，enqueue_highlight_script()会先检查project_id是否为空：只有配置了合法的 Project ID，插件才会向前台注入 Highlight 脚本，否则什么都不加载。

高级配置项

配置项	默认值	说明	源码依据
Service Name（服务名）	`highlight-wordpress`	用于标识不同环境或站点，便于在 Highlight 控制台按服务筛选数据	highlight-io.php`service_name_callback()`
Tracing Origins（追踪源）	`true`	控制哪些域名会被追踪；对多子域名或外部服务的复杂架构很有用。支持每行一个值，填`true`表示追踪当前域名所有请求	`tracing_origins_callback()`、`parse_tracing_origins()`
Enable Network Recording（网络录制）	开启	捕获网络请求与响应，录制内容可在会话回放的 "Network" 标签页查看	`enable_network_recording_callback()`
Backend URL（后端地址）	空	自定义数据上报地址，仅在自托管 Highlight 时使用	`backend_url_callback()`

Tracing Origins 的解析规则

parse_tracing_origins()的实现决定了该字段的行为：输入按换行符拆分并逐行trim，若列表中出现字符串true，则直接返回布尔值true（即追踪当前域名下的所有请求）；否则把每行作为一个字符串编码为 JSON 数组。这与前端 SDKH.init的tracingOrigins参数类型boolean | (string | RegExp)[]完全对应——命中列表中子串或正则的请求会被附加X-Highlight-Request请求头，从而把后端错误关联回对应会话。

Network Recording 的完整配置

网络录制开启时，插件会同时把recordHeadersAndBody固定置为true（见enqueue_highlight_script()中networkRecording配置），即记录请求/响应头与正文，方便完整还原 API 调试现场。

前端 SDK 完整参数参考

插件最终生成的是对H.init(projectId, options)的调用。options各字段的完整语义与更多可选参数（如manualStart、privacySetting、urlBlocklist、inlineImages等）见 Client SDK API 参考，其中与 WordPress 场景最相关的几个：

serviceName：应用名称，对应插件里的 Service Name；
tracingOrigins：后端所在域匹配列表，对应插件里的 Tracing Origins；
networkRecording：{ enabled, recordHeadersAndBody }，对应网络录制开关；
backendUrl：自托管实例的接收地址，对应插件里的 Backend URL。

工作原理：插件如何把 Highlight 注入 WordPress

插件的核心逻辑全部集中在 highlight-io.php 的Highlight_WP_Plugin类中，其运行流程如下：

注册钩子：构造函数通过add_action/add_filter挂载管理菜单（admin_menu）、设置初始化（admin_init）、前台脚本注入（wp_enqueue_scripts）以及插件列表页的"设置"快捷入口；
注册设置：page_init()注册highlight_wp_options选项组与各设置字段，并绑定sanitize()做输入清洗（含 nonce 校验、sanitize_text_field、esc_url_raw等）；
前台注入：enqueue_highlight_script()在满足"已配置 Project ID"条件时：
- 通过wp_enqueue_script加载插件目录下的highlight.js（Highlight 前端 SDK 的 UMD 构建产物）；
- 通过wp_add_inline_script(..., 'after')在 SDK 之后追加内联初始化脚本，实际生成形如H.init("YOUR_PROJECT_ID", {"serviceName":"highlight-wordpress","tracingOrigins":true,"networkRecording":{"enabled":true,"recordHeadersAndBody":true}});的代码；
激活引导：激活插件后自动跳转到设置页（register_activation_hook+ 重定向钩子）；
卸载清理：uninstall.php在卸载时调用delete_option('highlight_wp_options')，不留残留数据。

换句话说：只要配置了 Project ID，前台每个页面都会自动带上 Highlight 脚本并开始录制，无需修改主题或手工插入代码。

构建与打包

插件目录里的highlight.js是构建产物，由仓库根 package.json 中的build:wordpress脚本生成：

# 使用 yarn yarn build:wordpress # 使用 npm npm run build:wordpress

该脚本实际执行两步（见 package.json 第 40 行）：先把sdk/highlight-run/dist/index.umd.js（Highlight 浏览器端 SDK 的 UMD 打包）复制为highlight-io/highlight.js，再将整个插件目录打包为sdk/highlight-wordpress/highlight-io.zip，即得到可直接上传 WordPress 插件市场的发布包。

本地开发与端到端测试

仓库提供了完整的 Docker 化 WordPress 测试环境（见 e2e/wordpress 与 docker-compose.yml），适合在接入生产环境前先做验证：

# 进入 e2e/wordpress 目录后启动 WordPress + MySQL docker-compose up -d

环境由wordpress:latest与mysql:5.7两个容器组成，WordPress 映射到http://localhost:8000；
插件目录通过 volume 挂载（../../sdk/highlight-wordpress/highlight-io→wp-content/plugins/highlight-io），本地改代码即可即时生效，无需重建容器；
完成 WordPress 安装后，在http://localhost:8000/wp-admin登录后台并激活插件即可开始联调；
停止环境用docker-compose down；连同数据库一起清除用docker-compose down -v；
排查问题可先确认 Docker 正常运行，再通过docker-compose logs查看容器日志，插件改动未生效时用docker-compose restart重启容器。

该环境仅用于开发与测试，不应部署到生产。

最佳实践

先在预发布环境测试：上线生产前，务必在 staging 环境验证插件的注入与录制行为，避免影响真实流量；
定期审视追踪范围与网络录制：Tracing Origins 与网络录制会采集较多数据，建议按需开启，在"采集必要数据"与"尊重用户隐私"之间取得平衡；
使用有辨识度的服务名：为不同站点/环境设置不同的 Service Name，便于在 Highlight 控制台的会话列表与错误列表中快速区分；
关注隐私合规：插件会把会话数据（含交互与错误）发送至 Highlight 服务器。在启用前应了解数据收集范围（见 readme.txt 的 "Third-Party Services" 与 "Data Collection and Privacy" 小节），并在站点隐私政策中向用户说明数据采集行为、配置合适的同意机制，同时按需在 Highlight 控制台调整数据保留策略；
控制台日志属于敏感数据：若站点存在敏感信息被打印到 console 的情况，可结合前端 SDK 的disableConsoleRecording等参数权衡，详见 Client SDK API 参考。

故障排查

遇到问题时按以下顺序检查：

Project ID 是否正确：Project ID 填错或留空时，enqueue_highlight_script()不会注入任何脚本，前台将完全无监控数据。请到 app.highlight.io/setup 核对项目 ID；
插件是否激活且为最新版：确认插件在"插件"页处于启用状态，并保持更新到最新版本；
浏览器控制台是否有报错：打开开发者工具检查 console，看是否有 JavaScript 错误干扰 Highlight 脚本加载（例如主题或其它插件引发的冲突）；
网络录制是否与其它插件冲突：若启用了网络录制，需确认它没有与站点的安全插件、CSP 策略或其它拦截机制冲突，否则可能导致请求被阻断或录制不全；
检查脚本是否注入成功：查看前台页面源码，确认highlight.js与内联的H.init(...)调用存在，可快速区分"插件未生效"与"数据上报异常"两类问题。

若确认是自托管部署，还需在插件设置中正确填写Backend URL，指向自建的 Highlight 后端实例，否则数据不会发送到你的私有实例。