LogRocket 安装与配置 #

准备工作 #

在开始之前，你需要：

一个 LogRocket 账户（可以在 logrocket.com 免费注册）
一个应用 ID（App ID）

获取 App ID #

text

┌─────────────────────────────────────────────────────────────┐
│                    获取 App ID                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 登录 LogRocket 控制台                                    │
│  2. 创建新项目或选择现有项目                                  │
│  3. 在项目设置中找到 App ID                                  │
│                                                             │
│  App ID 格式：                                               │
│  xxxxxxxx/xxxxxxx                                           │
│                                                             │
│  示例：                                                     │
│  abcdefgh/ijklmnop                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

安装 SDK #

使用 npm/yarn #

bash

# npm
npm install logrocket --save

# yarn
yarn add logrocket

# pnpm
pnpm add logrocket

使用 CDN #

html

<script src="https://cdn.lr-ingest.io/LogRocket.min.js" crossorigin="anonymous"></script>
<script>
  window.LogRocket && window.LogRocket.init('your-app-id');
</script>

基础配置 #

最简配置 #

javascript

import LogRocket from 'logrocket';

LogRocket.init('your-app-id/app-name');

完整配置 #

javascript

import LogRocket from 'logrocket';

LogRocket.init('your-app-id/app-name', {
  release: '1.0.0',
  
  console: {
    isEnabled: true,
    isError: true,
    isWarn: true,
    isInfo: true,
    isDebug: false,
    isLog: true
  },
  
  network: {
    isEnabled: true,
    requestSanitizer: (request) => {
      if (request.url.includes('/api/auth')) {
        return null;
      }
      return request;
    },
    responseSanitizer: (response) => {
      if (response.url.includes('/api/sensitive')) {
        return null;
      }
      return response;
    }
  },
  
  dom: {
    isEnabled: true,
    inputSanitizer: true,
    textSanitizer: true,
    baseHref: 'https://example.com'
  },
  
  shouldCaptureIP: true,
  
  shouldDebugLog: false
});

配置选项详解 #

release（版本号） #

text

┌─────────────────────────────────────────────────────────────┐
│                    release 配置                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  作用：标识当前部署的应用版本                                 │
│                                                             │
│  用途：                                                     │
│  - 追踪问题归属版本                                         │
│  - 比较不同版本的错误率                                     │
│  - 回滚决策支持                                             │
│                                                             │
│  推荐方式：                                                  │
│                                                             │
│  1. 使用 package.json 版本：                                │
│     release: process.env.npm_package_version                │
│                                                             │
│  2. 使用 CI/CD 环境变量：                                   │
│     release: process.env.GIT_COMMIT_SHA                     │
│                                                             │
│  3. 使用构建时间戳：                                        │
│     release: `${version}-${buildNumber}`                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

javascript

LogRocket.init('your-app-id/app-name', {
  release: process.env.npm_package_version
});

console（控制台） #

javascript

LogRocket.init('your-app-id/app-name', {
  console: {
    isEnabled: true,
    isError: true,
    isWarn: true,
    isInfo: true,
    isDebug: false,
    isLog: true
  }
});

text

┌─────────────────────────────────────────────────────────────┐
│                    console 配置说明                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  isEnabled: 是否启用控制台记录                               │
│  isError: 记录 console.error                                │
│  isWarn: 记录 console.warn                                  │
│  isInfo: 记录 console.info                                  │
│  isDebug: 记录 console.debug                                │
│  isLog: 记录 console.log                                    │
│                                                             │
│  建议：                                                     │
│  - 生产环境关闭 isDebug 减少数据量                          │
│  - 保留 isError 和 isWarn 用于错误追踪                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

network（网络请求） #

javascript

LogRocket.init('your-app-id/app-name', {
  network: {
    isEnabled: true,
    requestSanitizer: (request) => {
      if (request.body && request.body.password) {
        request.body.password = '[REDACTED]';
      }
      if (request.headers['Authorization']) {
        request.headers['Authorization'] = '[REDACTED]';
      }
      return request;
    },
    responseSanitizer: (response) => {
      if (response.body && response.body.token) {
        response.body.token = '[REDACTED]';
      }
      return response;
    }
  }
});

text

┌─────────────────────────────────────────────────────────────┐
│                    network 配置说明                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  isEnabled: 是否启用网络请求记录                             │
│                                                             │
│  requestSanitizer: 请求过滤器                               │
│  - 返回 null 则不记录该请求                                 │
│  - 可以修改请求内容                                         │
│  - 用于隐藏敏感信息                                         │
│                                                             │
│  responseSanitizer: 响应过滤器                              │
│  - 返回 null 则不记录该响应                                 │
│  - 可以修改响应内容                                         │
│  - 用于隐藏敏感信息                                         │
│                                                             │
│  常见敏感信息：                                              │
│  - 密码、Token、API Key                                     │
│  - 身份证号、银行卡号                                       │
│  - 个人隐私信息                                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

dom（DOM 记录） #

javascript

LogRocket.init('your-app-id/app-name', {
  dom: {
    isEnabled: true,
    inputSanitizer: true,
    textSanitizer: true,
    baseHref: 'https://example.com'
  }
});

text

┌─────────────────────────────────────────────────────────────┐
│                    dom 配置说明                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  isEnabled: 是否启用 DOM 记录                                │
│                                                             │
│  inputSanitizer: 输入内容过滤                               │
│  - true: 自动隐藏密码输入                                   │
│  - 函数: 自定义过滤逻辑                                     │
│                                                             │
│  textSanitizer: 文本内容过滤                                │
│  - true: 使用默认过滤规则                                   │
│  - 函数: 自定义过滤逻辑                                     │
│                                                             │
│  baseHref: 基础 URL                                         │
│  - 用于解析相对路径                                         │
│                                                             │
│  自定义过滤示例：                                            │
│                                                             │
│  inputSanitizer: (el, value) => {                          │
│    if (el.id === 'credit-card') {                          │
│      return '****';                                         │
│    }                                                        │
│    return value;                                            │
│  }                                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

自定义 inputSanitizer #

javascript

LogRocket.init('your-app-id/app-name', {
  dom: {
    inputSanitizer: (el, value) => {
      if (el.type === 'password') {
        return '';
      }
      if (el.id === 'credit-card' || el.name === 'creditCard') {
        return value.replace(/\d(?=\d{4})/g, '*');
      }
      if (el.id === 'ssn' || el.name === 'socialSecurityNumber') {
        return '***-**-****';
      }
      return value;
    }
  }
});

框架集成 #

React 集成 #

基础集成 #

javascript

import React from 'react';
import ReactDOM from 'react-dom/client';
import LogRocket from 'logrocket';
import App from './App';

LogRocket.init('your-app-id/app-name');

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

React Error Boundary #

javascript

import React from 'react';
import LogRocket from 'logrocket';

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    LogRocket.captureException(error, {
      extra: {
        componentStack: errorInfo.componentStack
      }
    });
  }

  render() {
    if (this.state.hasError) {
      return <h1>Something went wrong.</h1>;
    }
    return this.props.children;
  }
}

export default ErrorBoundary;

使用 Error Boundary #

javascript

import ErrorBoundary from './ErrorBoundary';
import App from './App';

function Root() {
  return (
    <ErrorBoundary>
      <App />
    </ErrorBoundary>
  );
}

Vue 集成 #

Vue 3 集成 #

javascript

import { createApp } from 'vue';
import LogRocket from 'logrocket';
import App from './App.vue';

LogRocket.init('your-app-id/app-name');

const app = createApp(App);

app.config.errorHandler = (err, vm, info) => {
  LogRocket.captureException(err, {
    extra: {
      componentName: vm?.$options?.name,
      info: info
    }
  });
};

app.mount('#app');

Vue 2 集成 #

javascript

import Vue from 'vue';
import LogRocket from 'logrocket';
import App from './App.vue';

LogRocket.init('your-app-id/app-name');

Vue.config.errorHandler = (err, vm, info) => {
  LogRocket.captureException(err, {
    extra: {
      componentName: vm?.$options?.name,
      info: info
    }
  });
};

new Vue({
  render: h => h(App)
}).$mount('#app');

Angular 集成 #

安装 #

bash

npm install logrocket @logrocket/angular

配置 #

typescript

import { NgModule, ErrorHandler } from '@angular/core';
import LogRocket from 'logrocket';
import createErrorHandler from '@logrocket/angular';

LogRocket.init('your-app-id/app-name');

@NgModule({
  providers: [
    {
      provide: ErrorHandler,
      useFactory: () => createErrorHandler(LogRocket)
    }
  ]
})
export class AppModule { }

Next.js 集成 #

创建 LogRocket 初始化文件 #

javascript

import LogRocket from 'logrocket';

let initialized = false;

export function initLogRocket() {
  if (initialized || typeof window === 'undefined') return;
  
  LogRocket.init('your-app-id/app-name', {
    release: process.env.npm_package_version
  });
  
  initialized = true;
}

export { LogRocket };

在 _app.js 中初始化 #

javascript

import { useEffect } from 'react';
import { initLogRocket } from '../lib/logrocket';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    if (process.env.NODE_ENV === 'production') {
      initLogRocket();
    }
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

Nuxt.js 集成 #

创建插件 #

javascript

import LogRocket from 'logrocket';

export default (context, inject) => {
  if (process.client && process.env.NODE_ENV === 'production') {
    LogRocket.init('your-app-id/app-name', {
      release: process.env.npm_package_version
    });
    
    inject('logRocket', LogRocket);
  }
};

注册插件 #

javascript

export default {
  plugins: [
    { src: '~/plugins/logrocket.js', mode: 'client' }
  ]
};

状态管理集成 #

Redux 集成 #

bash

npm install @logrocket/redux

javascript

import { createStore, applyMiddleware, compose } from 'redux';
import LogRocket from 'logrocket';
import createLogRocketMiddleware from '@logrocket/redux';

LogRocket.init('your-app-id/app-name');

const store = createStore(
  rootReducer,
  initialState,
  compose(
    applyMiddleware(
      createLogRocketMiddleware(),
      thunk,
    )
  )
);

export default store;

Vuex 集成 #

javascript

import { createStore } from 'vuex';
import LogRocket from 'logrocket';

LogRocket.init('your-app-id/app-name');

const store = createStore({
  state() {
    return {
      count: 0
    };
  },
  mutations: {
    increment(state) {
      state.count++;
    }
  },
  plugins: [
    store => {
      store.subscribe((mutation, state) => {
        LogRocket.log('Vuex mutation:', mutation.type, state);
      });
    }
  ]
});

export default store;

Pinia 集成 #

javascript

import { createPinia } from 'pinia';
import LogRocket from 'logrocket';

LogRocket.init('your-app-id/app-name');

const pinia = createPinia();

pinia.use(({ store }) => {
  store.$onAction(({ name, args, after, onError }) => {
    LogRocket.log(`Pinia action: ${name}`, args);
    
    after((result) => {
      LogRocket.log(`Pinia action result: ${name}`, result);
    });
    
    onError((error) => {
      LogRocket.captureException(error, {
        extra: {
          action: name,
          args: args
        }
      });
    });
  });
});

export default pinia;

用户识别 #

设置用户信息 #

javascript

LogRocket.identify('user-123', {
  name: 'John Doe',
  email: 'john@example.com',
  subscriptionType: 'premium',
  createdAt: '2024-01-01'
});

text

┌─────────────────────────────────────────────────────────────┐
│                    用户识别配置                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  LogRocket.identify(userId, userTraits)                     │
│                                                             │
│  userId: 用户唯一标识                                       │
│  - 必须是字符串                                             │
│  - 应该是稳定的（不会变化）                                 │
│  - 通常使用数据库主键                                       │
│                                                             │
│  userTraits: 用户属性                                       │
│  - name: 用户名                                             │
│  - email: 邮箱                                              │
│  - 自定义属性: 任意业务相关属性                              │
│                                                             │
│  注意事项：                                                  │
│  - 不要在未登录时调用                                       │
│  - 登录后立即调用                                           │
│  - 用户信息更新时重新调用                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

用户登录后设置 #

javascript

async function login(credentials) {
  const response = await fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify(credentials)
  });
  
  const user = await response.json();
  
  LogRocket.identify(user.id, {
    name: user.name,
    email: user.email,
    role: user.role
  });
  
  return user;
}

用户登出 #

javascript

function logout() {
  LogRocket.identify(null);
}

环境区分 #

按环境配置 #

javascript

const LOGROCKET_APP_ID = {
  development: 'dev-app-id/dev',
  staging: 'staging-app-id/staging',
  production: 'prod-app-id/prod'
};

const currentEnv = process.env.NODE_ENV || 'development';

if (currentEnv === 'production') {
  LogRocket.init(LOGROCKET_APP_ID[currentEnv], {
    release: process.env.npm_package_version,
    console: {
      isEnabled: true,
      isDebug: false
    }
  });
}

使用环境变量 #

javascript

if (process.env.REACT_APP_LOGROCKET_APP_ID) {
  LogRocket.init(process.env.REACT_APP_LOGROCKET_APP_ID, {
    release: process.env.REACT_APP_VERSION
  });
}

text

┌─────────────────────────────────────────────────────────────┐
│                    环境变量配置                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  .env.production                                            │
│  REACT_APP_LOGROCKET_APP_ID=your-app-id/app-name           │
│  REACT_APP_VERSION=1.0.0                                    │
│                                                             │
│  .env.development                                           │
│  REACT_APP_LOGROCKET_APP_ID=                                │
│                                                             │
│  建议：                                                     │
│  - 开发环境不初始化 LogRocket                               │
│  - 测试环境使用独立项目                                     │
│  - 生产环境完整配置                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

验证安装 #

检查 SDK 加载 #

javascript

if (typeof LogRocket !== 'undefined') {
  console.log('LogRocket SDK loaded successfully');
} else {
  console.error('LogRocket SDK failed to load');
}

测试事件记录 #

javascript

LogRocket.init('your-app-id/app-name');

LogRocket.log('Test log message');
LogRocket.info('Test info message');
LogRocket.warn('Test warning message');
LogRocket.error('Test error message');

LogRocket.track('Test Event', {
  property: 'value'
});

检查控制台 #

打开 LogRocket 控制台，确认：

会话正在记录
事件已上报
用户信息正确显示

常见问题 #

1. SDK 加载失败 #

text

问题：控制台报错 "LogRocket is not defined"

解决方案：
1. 检查 CDN 链接是否正确
2. 确保在 SDK 加载后调用 init
3. 检查网络连接

2. 会话未记录 #

text

问题：控制台看不到会话记录

解决方案：
1. 检查 App ID 是否正确
2. 确认 init() 已被调用
3. 检查是否被广告拦截器阻止
4. 确认域名已在 LogRocket 中配置

3. 敏感信息泄露 #

text

问题：密码等敏感信息被记录

解决方案：
1. 配置 inputSanitizer
2. 配置 network.requestSanitizer
3. 配置 network.responseSanitizer

下一步 #

现在你已经完成了 LogRocket 的安装与配置，接下来学习基础使用了解如何使用 LogRocket 的核心功能！