企业官网建设流程全解析

• 可观测性
• 后端

本篇技术指南基于 highlight.io 开源仓库中的 Nest.js 快速开始文档（docs-content/getting-started/4_server/2_js/nestjs.md）及其配套 QuickStart 内容展开。highlight.io 是一款开源的全栈可观测性平台，统一提供错误监控（Error Monitoring）、会话回放（Session Replay）、日志（Logging）与分布式追踪（Distributed Tracing）。本文聚焦其服务端 JavaScript SDK 在 Nest.js 场景下的接入，读完本文你将掌握：如何安装@highlight-run/nestSDK、初始化配置参数的含义、如何通过全局拦截器捕获后端异常、如何手动上报错误、如何用自定义 Logger 采集日志，以及整个接入链路在源码层面的工作原理。

接入前置条件

在开始接入 Nest.js 之前，需要先在 highlight.io 平台创建一个项目并获取你的Project ID（形如<YOUR_PROJECT_ID>），该 ID 是所有初始化配置的核心参数。仓库中提供了完整的快速开始目录结构，服务端 JS 各框架的接入说明位于 docs-content/getting-started/4_server/2_js，Nest.js 的 QuickStart 内容定义在 highlight.io/components/QuickstartContent/server/js/nestjs.tsx。

同时，仓库在 highlight.io/middleware.ts 中维护了文档路由的兼容重定向，旧路径getting-started/backend-sdk/js/nestjs与getting-started/backend-logging/js/nestjs都会统一指向/docs/getting-started/server/js/nestjs，因此无论从哪个入口进入，看到的都是同一份 Nest.js 接入指南。

安装 Highlight SDK

Nest.js 场景下需要安装的是 Node.js 相关的@highlight-run/nest包。仓库中的jsGetSnippet辅助函数（定义于 highlight.io/components/QuickstartContent/server/js/shared-snippets-monitoring.tsx）会在页面上为每个 SDK slug 生成安装命令：

npm install --save @highlight-run/nest

该包是 highlight.io 为 Nest.js 框架提供的官方集成包，其实现位于仓库 sdk/highlight-nest/src/index.ts，内部依赖@highlight-run/node作为底层 SDK 引擎。

初始化 highlight.io 并注册全局拦截器

安装完成后，在应用的启动入口（通常是main.ts）中初始化 SDK，并注册HighlightInterceptor全局拦截器。这是 QuickStart 中给出的完整代码：

import { NestFactory } from '@nestjs/core'; import { AppModule } from './app.module'; import { HighlightInterceptor, H } from '@highlight-run/nest'; const env = { projectID: '<YOUR_PROJECT_ID>', serviceName: 'my-nestjs-app', serviceVersion: 'git-sha', environment: 'production', debug: false, }; async function bootstrap() { H.init(env); const app = await NestFactory.create(AppModule); app.useGlobalInterceptors(new HighlightInterceptor(env)); await app.listen(3000); } bootstrap();

H.init(env)负责初始化底层 Node SDK，app.useGlobalInterceptors(new HighlightInterceptor(env))则把拦截器注册为全局中间件，使所有 HTTP 请求都经过错误采集链路。需要注意：HighlightInterceptor构造时如果检测到 SDK 尚未初始化，会自动调用H.init(env)（见 sdk/highlight-nest/src/index.ts），因此即使忘记手动调用H.init，拦截器也会兜底完成初始化。

env 配置参数说明

QuickStart 中的env对象是 SDK 的标准配置项，各字段含义如下：

错误捕获原理：HighlightInterceptor 做了什么

从源码看，HighlightInterceptor实现了 NestJS 的NestInterceptor接口（sdk/highlight-nest/src/index.ts），其工作流程可以拆解为三步：

1. 开启请求 Span：在intercept方法中取出 HTTP 上下文，调用NodeH.startWithHeaders(...)以${request.method} ${request.url}为名开启一个追踪 Span，并把http.method、http.url写入 Span 属性，同时通过api.context.bind把 OpenTelemetry 上下文绑定到后续处理器上——这正是分布式追踪得以串联请求的关键一步。
2. 捕获异常：对next.handle()返回的 Observable 管道挂载catchError，一旦下游处理器抛出错误，就调用NodeH.consumeError(err, ...)把异常连同当前请求 Span 上报到 highlight.io，然后原样throwError重新抛出，不会吞掉业务异常，Nest 自身的异常处理机制不受影响。
3. 结束 Span：在finalize回调中调用requestSpan.end()，无论请求成功还是失败，Span 都会被正确关闭。

因此 QuickStart 中注册的这个拦截器同时承担了错误监控与自动追踪两件事，这也是其标题"Use theHighlightErrorFiltermiddleware to capture backend errors"的实质含义。

手动上报错误

拦截器只能覆盖经过 Nest 路由管道的异常。如果需要在拦截器覆盖范围之外（例如定时任务、队列消费、消息处理器）上报错误，QuickStart 提供了手动上报方式：

const parsed = H.parseHeaders(request.headers) H.consumeError(error, parsed?.secureSessionId, parsed?.requestId)

H.parseHeaders会从请求头中解析出 highlight.io 的会话标识（secureSessionId）与请求标识（requestId），从而把后端错误关联到对应的前端会话与请求；H.consumeError则负责实际写入错误事件。这样即使错误发生在拦截器之外，也能保持与用户会话的上下文关联。

验证错误上报是否生效

接入完成后，需要验证 SDK 是否真的在报告错误。QuickStart 给出了一段可以直接放入 Nest.jsAppService的验证代码：

import { Injectable } from '@nestjs/common' @Injectable() export class AppService { getHello(): string { console.log('hello, world!') console.warn('whoa there! ', Math.random()) if (Math.random() < 0.2) { // error will be caught by the HighlightErrorFilter throw new Error(`a random error occurred! ${Math.random()}`) } return 'Hello World!' } }

该服务以 20% 的概率抛出一个随机错误，同时打印一条console.log与一条console.warn。访问对应的 API 处理器后，可以前往 highlight.io 控制台的错误列表页确认错误是否出现；控制台日志则会由下面的日志采集机制自动上报。

记录后端日志：HighlightLogger

日志是服务端可观测性的另一块拼图。Nest.js 的日志接入同样复用同一份初始化代码，只需注意日志场景下拦截器会额外承担日志转发职责。对应的日志 QuickStart 内容定义在 highlight.io/components/QuickstartContent/logging/js/nestjs.tsx，其核心说明是：使用HighlightLogger中间件把后端日志记录到 highlight.io。

从源码看，HighlightLogger继承自 NestJS 内置的ConsoleLogger，并重写了五个日志方法（sdk/highlight-nest/src/index.ts）：

每个方法都在调用父类输出控制台日志的同时，通过NodeH.log(message, level)把日志转发到 highlight.io，并做了异常兜底（上报失败只输出_debug提示，不影响应用正常运行）。这意味着应用内使用Logger、console.log等途径产生的日志都会自动被采集，无需逐个埋点。

HighlightLogger还实现了OnApplicationShutdown，在应用关闭时调用NodeH.flush()确保内存中的日志与错误在进程退出前被完整冲刷。

分布式追踪：与前端会话自动串联

QuickStart 的entries中包含了verifyTraces验证步骤，配合HighlightInterceptor在第 1 步开启的请求 Span，后端每个 HTTP 请求都会成为一条可追踪的链路。由于H.parseHeaders可以从入站请求头还原前端会话与请求 ID，前后端数据能够在追踪视图中自动关联——即前端会话回放、后端错误、日志与追踪可以围绕同一个用户请求完整串联，这正是 highlight.io "全栈监控" 的核心体验。关于追踪的上报与验证细节，仓库还提供了独立的追踪快速开始模板（见 highlight.io/components/QuickstartContent/shared-snippets-tracing.tsx）。

进阶：使用 HighlightModule 以模块化方式接入

除了手动初始化与注册全局拦截器，SDK 还提供了 Nest 模块化的接入方式。HighlightModule（sdk/highlight-nest/src/index.ts）暴露了两个静态方法：

• HighlightModule.forRoot(options)：同步注册，内部初始化 Node SDK，并把HighlightLogger与HighlightInterceptor同时注册为 provider 并导出；
• HighlightModule.forRootAsync(options)：异步变体，同样完成初始化与 provider 注册。

两种方式都内置了幂等判断（if (!NodeH.isInitialized())），不会重复初始化 SDK。在AppModule的imports中引入HighlightModule.forRoot(env)，即可在依赖注入体系中直接使用HighlightLogger与HighlightInterceptor，更适合大型 Nest.js 工程的模块化管理。

结语：一次接入，三面覆盖

从 highlight.io/components/QuickstartContent/server/js/nestjs.tsx 可以看出，Nest.js 快速开始共包含 6 个步骤：前端安装、SDK 安装、注册拦截器、手动错误上报、错误验证、日志验证，最终同时覆盖 Errors、Logs、Traces 三个产品能力。接入的核心就是三件事：

1. npm install @highlight-run/nest安装 SDK；
2. 用H.init(env)配置项目 ID 与服务元信息；
3. 注册HighlightInterceptor全局拦截器（错误 + 追踪），并借助HighlightLogger或继承ConsoleLogger的日志机制自动采集日志。

所有能力都有对应的源码实现可查（sdk/highlight-nest/src/index.ts），接入过程中若遇到问题，可先将debug置为true观察 SDK 内部上报日志，再结合控制台数据逐项排查。

• 可观测性
• 后端