tracekit-nextjs-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TraceKit Next.js SDK Setup

TraceKit Next.js SDK 安装配置

When To Use

适用场景

Use this skill when the user asks to:

Add TraceKit to a Next.js application
Add observability, error tracking, or APM to a Next.js project
Instrument a Next.js app with distributed tracing
Set up error monitoring in a Next.js app (App Router or Pages Router)
Configure server-side and client-side error capture in Next.js
Debug production Next.js applications with live breakpoints

If the user has a vanilla JavaScript/TypeScript project without Next.js, use the

tracekit-browser-sdk

skill instead. If the user has a plain React SPA (no Next.js), use the

tracekit-react-sdk

skill instead.

当用户提出以下需求时，使用本技能：

在Next.js应用中添加TraceKit
为Next.js项目添加可观测性、错误追踪或APM功能
为Next.js应用配置分布式追踪
在Next.js应用（App Router或Pages Router）中设置错误监控
配置Next.js的服务端和客户端错误捕获
通过实时断点调试生产环境中的Next.js应用

如果用户的项目是无Next.js的原生JavaScript/TypeScript项目，请使用

tracekit-browser-sdk

技能；如果是纯React单页应用（无Next.js），请使用

tracekit-react-sdk

技能。

Non-Negotiable Rules

必须遵守的规则

Never hardcode API keys in code. Use
```
NEXT_PUBLIC_TRACEKIT_API_KEY
```
for client-side and
```
TRACEKIT_API_KEY
```
for server-side via
```
.env.local
```
.
Always include a verification step confirming errors appear in
```
https://app.tracekit.dev
```
.
Always enable code monitoring (
```
enableCodeMonitoring: true
```
) -- it is TraceKit's differentiator.
Always initialize TraceKit before app bootstrap -- use Next.js instrumentation files for both client and server init.

切勿在代码中硬编码API密钥。客户端使用
```
NEXT_PUBLIC_TRACEKIT_API_KEY
```
，服务端通过
```
.env.local
```
使用
```
TRACEKIT_API_KEY
```
。
始终包含验证步骤，确认错误已出现在
```
https://app.tracekit.dev
```
中。
始终启用代码监控（
```
enableCodeMonitoring: true
```
）——这是TraceKit的核心差异化功能。
务必在应用启动前初始化TraceKit——使用Next.js的instrumentation文件分别初始化客户端和服务端。

Detection

项目类型检测

Before applying this skill, detect the project type:

Check
package.json
for
```
next
```
in dependencies -- confirms this is a Next.js project.
Detect router architecture by directory structure:
- ```
app/
```
  directory exists => App Router (Next.js 13+)
- ```
pages/
```
  directory exists => Pages Router
- Both may exist (hybrid) -- cover both patterns
Only ask the user if neither
```
app/
```
nor
```
pages/
```
directory is found.

应用本技能前，先检测项目类型：

**检查
```
package.json
```
**中的依赖是否包含
```
next
```
——确认这是Next.js项目。
通过目录结构检测路由架构：
- 存在
```
app/
```
  目录 => App Router（Next.js 13+）
- 存在
```
pages/
```
  目录 => Pages Router
- 两者可能同时存在（混合模式）——需覆盖两种模式
仅当未找到
app/
和
pages/
目录时，才询问用户。

Step 1: Environment Setup

步骤1：环境配置

Set API keys in

.env.local

(Next.js convention -- never committed to git):

bash

undefined

在

.env.local

中设置API密钥（Next.js约定——切勿提交到git）：

bash

undefined

.env.local

NEXT_PUBLIC_TRACEKIT_API_KEY=ctxio_your_api_key_here TRACEKIT_API_KEY=ctxio_your_server_api_key_here APP_VERSION=1.0.0 NEXT_PUBLIC_APP_VERSION=1.0.0


- `NEXT_PUBLIC_` prefix makes the variable available to client-side code (browser bundle).
- Without the prefix, the variable is only available server-side.
- Use the same key for both, or separate keys for client vs server if your security model requires it.

Where to get your API key:
1. Log in to [TraceKit](https://app.tracekit.dev)
2. Go to **API Keys** page
3. Generate a new key (starts with `ctxio_`)

NEXT_PUBLIC_TRACEKIT_API_KEY=ctxio_your_api_key_here TRACEKIT_API_KEY=ctxio_your_server_api_key_here APP_VERSION=1.0.0 NEXT_PUBLIC_APP_VERSION=1.0.0


- `NEXT_PUBLIC_`前缀使变量可用于客户端代码（浏览器包）。
- 无前缀的变量仅可用于服务端。
- 可对客户端和服务端使用相同密钥，若安全模型要求，也可使用不同密钥。

获取API密钥的方式：
1. 登录[TraceKit](https://app.tracekit.dev)
2. 进入**API Keys**页面
3. 生成新密钥（以`ctxio_`开头）

Step 2: Install SDK

步骤2：安装SDK

bash

npm install @tracekit/nextjs

Or with Yarn:

bash

yarn add @tracekit/nextjs

This installs the TraceKit Next.js wrapper with multi-runtime support (client + server), error boundary components, navigation breadcrumbs, and source map upload tooling.

bash

npm install @tracekit/nextjs

或使用Yarn：

bash

yarn add @tracekit/nextjs

此命令将安装带有多运行时支持（客户端+服务端）、错误边界组件、导航面包屑和源映射上传工具的TraceKit Next.js封装包。

Step 3: Server-Side Init

步骤3：服务端初始化

Create

instrumentation.ts

at the project root. Next.js calls the

register()

function during server startup.

typescript

// instrumentation.ts
import { initServer, captureRequestError } from '@tracekit/nextjs';

export function register() {
  initServer({
    apiKey: process.env.TRACEKIT_API_KEY!,
    release: process.env.APP_VERSION,
    environment: process.env.NODE_ENV,
    apiEndpoint: 'https://app.tracekit.dev',
    enableCodeMonitoring: true,
  });
}

// Capture server-side request errors (App Router + Pages Router)
export const onRequestError = captureRequestError;

captureRequestError

matches the Next.js

onRequestError

signature. It receives error context including

routerKind

("App Router" or "Pages Router"),

routePath

, and

routeType

("page", "route", or "middleware"). Errors are sent to TraceKit via HTTP POST (fire-and-forget, never throws).

在项目根目录创建

instrumentation.ts

文件。Next.js会在服务启动时调用

register()

函数。

typescript

// instrumentation.ts
import { initServer, captureRequestError } from '@tracekit/nextjs';

export function register() {
  initServer({
    apiKey: process.env.TRACEKIT_API_KEY!,
    release: process.env.APP_VERSION,
    environment: process.env.NODE_ENV,
    apiEndpoint: 'https://app.tracekit.dev',
    enableCodeMonitoring: true,
  });
}

// 捕获服务端请求错误（App Router + Pages Router）
export const onRequestError = captureRequestError;

captureRequestError

匹配Next.js的

onRequestError

签名，接收包含

routerKind

（"App Router"或"Pages Router"）、

routePath

和

routeType

（"page"、"route"或"middleware"）的错误上下文。错误会通过HTTP POST发送到TraceKit（即发即弃，不会抛出异常）。

Step 4: Client-Side Init

步骤4：客户端初始化

Create

instrumentation-client.ts

at the project root. Next.js loads this file in the browser.

typescript

// instrumentation-client.ts
import { initClient, onRouterTransitionStart } from '@tracekit/nextjs';

initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  environment: process.env.NODE_ENV,
  endpoint: 'https://app.tracekit.dev/v1/traces',
  enableCodeMonitoring: true,
  tracePropagationTargets: [
    process.env.NEXT_PUBLIC_API_URL || 'https://api.example.com',
  ],
});

// Next.js 15.3+ navigation breadcrumbs
export { onRouterTransitionStart };

initClient()

initializes the

@tracekit/browser

SDK for client-side error capture, breadcrumbs, and distributed tracing.

onRouterTransitionStart

is a Next.js 15.3+ hook that captures client-side route transitions as breadcrumbs with from/to URLs and navigation type (push, replace, traverse).

在项目根目录创建

instrumentation-client.ts

文件。Next.js会在浏览器中加载此文件。

typescript

// instrumentation-client.ts
import { initClient, onRouterTransitionStart } from '@tracekit/nextjs';

initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  environment: process.env.NODE_ENV,
  endpoint: 'https://app.tracekit.dev/v1/traces',
  enableCodeMonitoring: true,
  tracePropagationTargets: [
    process.env.NEXT_PUBLIC_API_URL || 'https://api.example.com',
  ],
});

// Next.js 15.3+ 导航面包屑
export { onRouterTransitionStart };

initClient()

初始化

@tracekit/browser

SDK，用于客户端错误捕获、面包屑和分布式追踪。

onRouterTransitionStart

是Next.js 15.3+的钩子，可捕获客户端路由切换作为面包屑，包含来源/目标URL和导航类型（push、replace、traverse）。

Step 5: Error Boundary

步骤5：错误边界

App Router

Create

app/global-error.tsx

to capture errors in the root layout:

typescript

// app/global-error.tsx
export { GlobalError as default } from '@tracekit/nextjs';

Or customize the error UI:

typescript

// app/global-error.tsx
'use client';

import { useEffect } from 'react';
import { captureException } from '@tracekit/nextjs';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={reset}>Try again</button>
      </body>
    </html>
  );
}

For per-route error boundaries, create

error.tsx

files in route directories:

typescript

// app/dashboard/error.tsx
'use client';

import { useEffect } from 'react';
import { captureException } from '@tracekit/nextjs';

export default function DashboardError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    captureException(error);
  }, [error]);

  return (
    <div>
      <h2>Dashboard error</h2>
      <button onClick={reset}>Retry</button>
    </div>
  );
}

创建

app/global-error.tsx

以捕获根布局中的错误：

typescript

// app/global-error.tsx
export { GlobalError as default } from '@tracekit/nextjs';

或自定义错误UI：

typescript

// app/global-error.tsx
'use client';

import { useEffect } from 'react';
import { captureException } from '@tracekit/nextjs';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <h2>出现错误！</h2>
        <button onClick={reset}>重试</button>
      </body>
    </html>
  );
}

如需为单个路由设置错误边界，在路由目录中创建

error.tsx

文件：

typescript

// app/dashboard/error.tsx
'use client';

import { useEffect } from 'react';
import { captureException } from '@tracekit/nextjs';

export default function DashboardError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    captureException(error);
  }, [error]);

  return (
    <div>
      <h2>仪表盘错误</h2>
      <button onClick={reset}>重试</button>
    </div>
  );
}

Pages Router

Wrap your custom error page with

withTraceKitErrorPage

typescript

// pages/_error.tsx
import { withTraceKitErrorPage } from '@tracekit/nextjs';

function CustomErrorPage({ statusCode }: { statusCode?: number }) {
  return (
    <div>
      <h1>{statusCode ? statusCode + ' - Server Error' : 'Client Error'}</h1>
      <p>An unexpected error occurred.</p>
    </div>
  );
}

CustomErrorPage.getInitialProps = ({ res, err }: any) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404;
  return { statusCode, err };
};

export default withTraceKitErrorPage(CustomErrorPage);

使用

withTraceKitErrorPage

包裹自定义错误页面：

typescript

// pages/_error.tsx
import { withTraceKitErrorPage } from '@tracekit/nextjs';

function CustomErrorPage({ statusCode }: { statusCode?: number }) {
  return (
    <div>
      <h1>{statusCode ? statusCode + ' - 服务端错误' : '客户端错误'}</h1>
      <p>发生了意外错误。</p>
    </div>
  );
}

CustomErrorPage.getInitialProps = ({ res, err }: any) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404;
  return { statusCode, err };
};

export default withTraceKitErrorPage(CustomErrorPage);

Step 6: Custom Error Capture and Performance Spans

步骤6：自定义错误捕获和性能追踪

Client-side (client components, event handlers):

typescript

import { captureException, setUser } from '@tracekit/nextjs';

// Capture errors manually
try {
  await riskyOperation();
} catch (err) {
  captureException(err as Error, { context: 'checkout' });
}

// Set user context after authentication
setUser({ id: user.id, email: user.email });

Server-side (API routes, server components) -- use

captureRequestError

for automatic capture, or import from Node SDK for manual spans in API routes:

typescript

// app/api/orders/route.ts
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const order = await processOrder(body);
    return NextResponse.json(order);
  } catch (err) {
    // Server errors are automatically captured via captureRequestError
    return NextResponse.json({ error: 'Failed' }, { status: 500 });
  }
}

Re-exported functions available from

@tracekit/nextjs

(client-side only):

typescript

import {
  captureException,
  captureMessage,
  setUser,
  setTag,
  setExtra,
  addBreadcrumb,
  getClient,
} from '@tracekit/nextjs';

These re-exports are client-side functions from

@tracekit/browser

. Do not use them in server-side code (API routes, server components). For server-side error capture, use

captureRequestError

客户端（客户端组件、事件处理函数）：

typescript

import { captureException, setUser } from '@tracekit/nextjs';

// 手动捕获错误
try {
  await riskyOperation();
} catch (err) {
  captureException(err as Error, { context: 'checkout' });
}

// 认证后设置用户上下文
setUser({ id: user.id, email: user.email });

服务端（API路由、服务端组件）——使用

captureRequestError

自动捕获，或从Node SDK导入以在API路由中手动设置追踪：

typescript

// app/api/orders/route.ts
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const order = await processOrder(body);
    return NextResponse.json(order);
  } catch (err) {
    // 服务端错误会通过captureRequestError自动捕获
    return NextResponse.json({ error: '失败' }, { status: 500 });
  }
}

@tracekit/nextjs
提供的可重导出函数（仅客户端可用）：

typescript

import {
  captureException,
  captureMessage,
  setUser,
  setTag,
  setExtra,
  addBreadcrumb,
  getClient,
} from '@tracekit/nextjs';

这些重导出的函数来自

@tracekit/browser

的客户端函数，请勿在服务端代码（API路由、服务端组件）中使用。服务端错误捕获请使用

captureRequestError

。

Step 7: Distributed Tracing

步骤7：分布式追踪

Client-side distributed tracing is configured via

tracePropagationTargets

in the

initClient()

call (Step 4). The SDK automatically adds trace headers (

tracekit-trace-id

baggage

) to outgoing

fetch

requests matching the targets.

typescript

// instrumentation-client.ts
initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  endpoint: 'https://app.tracekit.dev/v1/traces',
  enableCodeMonitoring: true,
  tracePropagationTargets: [
    'https://api.example.com',
    /^\/api\//,  // Same-origin API routes
  ],
});

Server-side API routes are automatically traced via

captureRequestError

with route context (

routerKind

routePath

routeType

客户端分布式追踪通过

initClient()

调用中的

tracePropagationTargets

配置（步骤4）。SDK会自动为匹配目标的

fetch

请求添加追踪头（

tracekit-trace-id

、

baggage

）。

typescript

// instrumentation-client.ts
initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  endpoint: 'https://app.tracekit.dev/v1/traces',
  enableCodeMonitoring: true,
  tracePropagationTargets: [
    'https://api.example.com',
    /^\/api\//,  // 同域API路由
  ],
});

服务端API路由会通过

captureRequestError

自动追踪，并附带路由上下文（

routerKind

、

routePath

、

routeType

）。

Step 8: Session Replay (Optional)

步骤8：会话重放（可选）

Enable session replay in the client-side init (browser only):

typescript

// instrumentation-client.ts
initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  endpoint: 'https://app.tracekit.dev/v1/traces',
  enableCodeMonitoring: true,
  replay: {
    enabled: true,
    sampleRate: 0.1,
    errorSampleRate: 1.0,
    maskAllText: true,
    blockAllMedia: false,
  },
});

Session replay captures DOM mutations, network requests, and console logs in the browser. It does not affect server-side rendering.

在客户端初始化中启用会话重放（仅浏览器端）：

typescript

// instrumentation-client.ts
initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  endpoint: 'https://app.tracekit.dev/v1/traces',
  enableCodeMonitoring: true,
  replay: {
    enabled: true,
    sampleRate: 0.1,
    errorSampleRate: 1.0,
    maskAllText: true,
    blockAllMedia: false,
  },
});

会话重放会捕获浏览器中的DOM变更、网络请求和控制台日志，不会影响服务端渲染。

Step 9: Source Maps (Optional)

步骤9：源映射（可选）

Add the TraceKit webpack plugin to

next.config.js

for automatic source map upload during builds:

javascript

// next.config.js
const { withTraceKit } = require('@tracekit/nextjs/webpack-plugin');

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your existing config
};

module.exports = withTraceKit(nextConfig, {
  apiKey: process.env.TRACEKIT_API_KEY,
  release: process.env.APP_VERSION || '1.0.0',
  // Source maps are uploaded during build, not at runtime
});

Or upload manually after building:

bash

tracekit sourcemaps upload \
  --api-key $TRACEKIT_API_KEY \
  --release 1.0.0 \
  --dist .next/static

在

next.config.js

中添加TraceKit webpack插件，以在构建期间自动上传源映射：

javascript

// next.config.js
const { withTraceKit } = require('@tracekit/nextjs/webpack-plugin');

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 现有配置
};

module.exports = withTraceKit(nextConfig, {
  apiKey: process.env.TRACEKIT_API_KEY,
  release: process.env.APP_VERSION || '1.0.0',
  // 源映射在构建期间上传，而非运行时
});

或在构建完成后手动上传：

bash

tracekit sourcemaps upload \
  --api-key $TRACEKIT_API_KEY \
  --release 1.0.0 \
  --dist .next/static

Step 10: Verification

步骤10：验证

After integrating, verify both client-side and server-side errors are captured:

Client-side: Add a button that throws an error in a client component:

typescript

'use client';
export default function TestPage() {
  return <button onClick={() => { throw new Error('TraceKit Next.js client test'); }}>Test Error</button>;
}

Server-side: Create an API route that throws:

typescript

// app/api/test-error/route.ts
export async function GET() {
  throw new Error('TraceKit Next.js server test');
}

Open
```
https://app.tracekit.dev
```
.
Confirm both errors appear within 30-60 seconds -- client errors show browser context, server errors show route context.

集成完成后，验证客户端和服务端错误是否被捕获：

客户端：在客户端组件中添加一个会抛出错误的按钮：

typescript

'use client';
export default function TestPage() {
  return <button onClick={() => { throw new Error('TraceKit Next.js client test'); }}>测试错误</button>;
}

服务端：创建一个会抛出错误的API路由：

typescript

// app/api/test-error/route.ts
export async function GET() {
  throw new Error('TraceKit Next.js server test');
}

打开
```
https://app.tracekit.dev
```
。
确认两个错误会在30-60秒内出现——客户端错误会显示浏览器上下文，服务端错误会显示路由上下文。

Complete Working Example (App Router)

完整可用示例（App Router）

All files needed for a full Next.js App Router setup:

bash

undefined

完整Next.js App Router配置所需的所有文件：

bash

undefined

.env.local

NEXT_PUBLIC_TRACEKIT_API_KEY=ctxio_your_api_key_here TRACEKIT_API_KEY=ctxio_your_server_api_key_here APP_VERSION=1.0.0 NEXT_PUBLIC_APP_VERSION=1.0.0


```typescript
// instrumentation-client.ts
import { initClient, onRouterTransitionStart } from '@tracekit/nextjs';

initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  environment: process.env.NODE_ENV,
  endpoint: 'https://app.tracekit.dev/v1/traces',
  enableCodeMonitoring: true,
  tracePropagationTargets: [
    process.env.NEXT_PUBLIC_API_URL || 'https://api.example.com',
  ],
  replay: {
    enabled: true,
    sampleRate: 0.1,
    errorSampleRate: 1.0,
  },
});

export { onRouterTransitionStart };

typescript

// instrumentation.ts
import { initServer, captureRequestError } from '@tracekit/nextjs';

export function register() {
  initServer({
    apiKey: process.env.TRACEKIT_API_KEY!,
    release: process.env.APP_VERSION,
    environment: process.env.NODE_ENV,
    enableCodeMonitoring: true,
  });
}

export const onRequestError = captureRequestError;

typescript

// app/global-error.tsx
export { GlobalError as default } from '@tracekit/nextjs';

typescript

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

NEXT_PUBLIC_TRACEKIT_API_KEY=ctxio_your_api_key_here TRACEKIT_API_KEY=ctxio_your_server_api_key_here APP_VERSION=1.0.0 NEXT_PUBLIC_APP_VERSION=1.0.0


```typescript
// instrumentation-client.ts
import { initClient, onRouterTransitionStart } from '@tracekit/nextjs';

initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  environment: process.env.NODE_ENV,
  endpoint: 'https://app.tracekit.dev/v1/traces',
  enableCodeMonitoring: true,
  tracePropagationTargets: [
    process.env.NEXT_PUBLIC_API_URL || 'https://api.example.com',
  ],
  replay: {
    enabled: true,
    sampleRate: 0.1,
    errorSampleRate: 1.0,
  },
});

export { onRouterTransitionStart };

typescript

// instrumentation.ts
import { initServer, captureRequestError } from '@tracekit/nextjs';

export function register() {
  initServer({
    apiKey: process.env.TRACEKIT_API_KEY!,
    release: process.env.APP_VERSION,
    environment: process.env.NODE_ENV,
    enableCodeMonitoring: true,
  });
}

export const onRequestError = captureRequestError;

typescript

// app/global-error.tsx
export { GlobalError as default } from '@tracekit/nextjs';

typescript

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Troubleshooting

故障排除

Server errors not appearing

服务端错误未显示

Check
instrumentation.ts
: Ensure

register()

calls

initServer()

and

onRequestError

is exported at the top level.

Check
TRACEKIT_API_KEY
is set in
```
.env.local
```
(without
```
NEXT_PUBLIC_
```
prefix for server-side).

Check outbound access: Server must reach

https://app.tracekit.dev

. Test with:

curl -X POST https://app.tracekit.dev/v1/traces

(expect 401).

检查
instrumentation.ts
：确保

register()

调用了

initServer()

，且

onRequestError

在顶层导出。

检查
TRACEKIT_API_KEY
：确保在
```
.env.local
```
中已设置（服务端无需
```
NEXT_PUBLIC_
```
前缀）。
检查出站访问：服务端必须能访问
```
https://app.tracekit.dev
```
。可通过
```
curl -X POST https://app.tracekit.dev/v1/traces
```
测试（预期返回401）。

Client errors not appearing

客户端错误未显示

Check
instrumentation-client.ts
: Ensure

initClient()

is called with

NEXT_PUBLIC_TRACEKIT_API_KEY

Check browser console for initialization errors or network failures to the TraceKit endpoint.

检查
instrumentation-client.ts
：确保

initClient()

使用

NEXT_PUBLIC_TRACEKIT_API_KEY

调用。

检查浏览器控制台：查看是否有初始化错误或连接TraceKit端点的网络失败。

Server vs client init confusion

服务端与客户端初始化混淆

Server:
```
instrumentation.ts
```
with
```
initServer()
```
-- runs in Node.js/Edge runtime
Client:
```
instrumentation-client.ts
```
with
```
initClient()
```
-- runs in the browser
Do not import server functions in client code or vice versa.

服务端：
```
instrumentation.ts
```
中使用
```
initServer()
```
——运行在Node.js/Edge运行时
客户端：
```
instrumentation-client.ts
```
中使用
```
initClient()
```
——运行在浏览器
请勿在客户端代码中导入服务端函数，反之亦然。

Edge runtime compatibility

Edge运行时兼容性

```
captureRequestError
```
uses
```
fetch()
```
internally, which is available in both Node.js and Edge runtimes.
```
initServer()
```
stores config in a module-scoped variable -- safe for both runtimes.

```
captureRequestError
```
内部使用
```
fetch()
```
，可在Node.js和Edge运行时中使用。
```
initServer()
```
将配置存储在模块作用域变量中——对两种运行时都安全。

Hydration errors

水化错误

TraceKit captures React recoverable hydration errors automatically via
```
onRecoverableError
```
in the client-side init.
These appear as "handled" errors with mechanism
```
react.onRecoverableError
```
.

TraceKit会通过客户端初始化中的
```
onRecoverableError
```
自动捕获React可恢复水化错误。
这些错误会显示为已处理错误，机制为
```
react.onRecoverableError
```
。

Navigation breadcrumbs not appearing

导航面包屑未显示

```
onRouterTransitionStart
```
requires Next.js 15.3+. On older versions, breadcrumbs are captured via the base
```
@tracekit/browser
```
navigation integration.

Ensure

onRouterTransitionStart

is re-exported from

instrumentation-client.ts

```
onRouterTransitionStart
```
需要Next.js 15.3+。在旧版本中，面包屑会通过基础
```
@tracekit/browser
```
的导航集成捕获。

确保

onRouterTransitionStart

已从

instrumentation-client.ts

中重导出。

Next Steps

后续步骤

Once your Next.js app is traced, consider:

Browser SDK -- For non-Next.js pages, use the
```
tracekit-browser-sdk
```
skill
React SDK -- For plain React SPAs, use the
```
tracekit-react-sdk
```
skill
Session Replay -- Record and replay user sessions with linked traces
Source Maps -- Upload source maps for readable production stack traces
Backend SDKs -- Connect frontend traces to backend services for full distributed tracing

当Next.js应用完成追踪配置后，可考虑：

Browser SDK——对于非Next.js页面，使用
```
tracekit-browser-sdk
```
技能
React SDK——对于纯React单页应用，使用
```
tracekit-react-sdk
```
技能
会话重放——录制并重放用户会话，关联追踪数据
源映射——上传源映射以获取可读的生产环境堆栈追踪
后端SDK——将前端追踪与后端服务连接，实现完整分布式追踪

References

参考资料

Next.js SDK docs:

https://app.tracekit.dev/docs/frontend/frameworks/nextjs

Browser SDK docs:

https://app.tracekit.dev/docs/frontend/browser-sdk

TraceKit docs root:
```
https://app.tracekit.dev/docs
```
Dashboard:
```
https://app.tracekit.dev
```

Next.js SDK文档：

https://app.tracekit.dev/docs/frontend/frameworks/nextjs

Browser SDK文档：

https://app.tracekit.dev/docs/frontend/browser-sdk

TraceKit文档主页：
```
https://app.tracekit.dev/docs
```
控制台：
```
https://app.tracekit.dev
```