Sentry JavaScript SDK 开发环境搭建与贡献指南

Sentry JavaScript SDK 开发环境搭建与贡献指南

sentry-javascript Official Sentry SDKs for JavaScript 项目地址: https://gitcode.com/gh_mirrors/se/sentry-javascript

项目概述

Sentry JavaScript SDK 是一个功能强大的错误监控工具，它由多个模块化包组成，采用 monorepo 架构管理。本文将为开发者详细介绍如何搭建开发环境、构建流程、测试方法等核心内容。

开发环境配置

工具链准备

项目推荐使用 Volta 工具来管理 Node.js 和包管理器的版本，确保开发环境一致性。主要依赖包括：

• Node.js（通过 Volta 管理版本）
• Yarn（包管理器）
• pnpm（可选，用于 E2E 测试）

初始化项目

由于采用 monorepo 结构，项目使用 Lerna 进行多包管理。初始化步骤如下：

1. 安装所有依赖：yarn
2. 执行初始构建：yarn build

这一步骤会编译所有 TypeScript 代码，确保类型系统正常工作。

构建系统详解

构建命令

项目提供多种构建选项：

1. 一次性构建：yarn build:dev - 编译所有包
2. 选择性构建：yarn build:dev:filter <包名> - 仅构建指定包及其依赖
3. 开发模式：yarn build:dev:watch - 推荐开发时使用，支持文件变更自动重建

生产构建

yarn build 命令会执行生产环境构建，生成可用于打包的代码（不包括发布到 NPM 的 tarball）。构建输出位于各包的 build/ 目录下，例如：

• packages/browser/build - 常规构建输出
• packages/browser/build/bundles - 打包后的文件

注意：生产构建的文件名可能随版本变化，升级时需仔细检查。

本地测试与调试

测试方法

有三种主要方式测试本地修改：

1. Yarn Link：创建符号链接到测试项目
2. Yalc：模拟已发布包的行为
3. Tarball：构建 tarball 后直接安装到测试项目

调试构建标志

代码中广泛使用 __DEBUG_BUILD__ 标志，其作用包括：

1. 从 CDN 打包版本中移除调试代码
2. 允许用户在自身构建中控制是否包含 Sentry 调试代码

构建过程中，该标志会被替换为 (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__)，用户可通过设置 __SENTRY_DEBUG__ 来控制调试代码的包含。

测试策略

测试要求

所有非琐碎的修复或功能都应包含测试。测试文件位于各包的 test 目录下，另有专门的集成测试目录：

• dev-packages/browser-integration-tests - 浏览器集成测试
• dev-packages/node-integration-tests - Node 集成测试
• dev-packages/e2e-tests - 端到端测试应用

执行测试

测试执行方式与构建类似：

• 根目录 yarn test：运行所有测试
• 特定包内 yarn test：运行该包测试

注意：执行测试前必须先运行 yarn build。

代码质量保障

代码检查

项目使用统一的 linting 规则：

• yarn lint：检查所有代码
• 包内 yarn lint：检查特定包

同样需要先执行构建才能进行 linting 检查。

开发建议

1. 遵循项目约定的提交、Issue 和 PR 规范
2. 非琐碎变更必须包含相应测试
3. 开发时推荐使用 watch 模式构建 (yarn build:dev:watch)
4. 注意 Python 版本兼容性，构建原生二进制需要 Python <3.12

通过以上指南，开发者可以快速搭建 Sentry JavaScript SDK 的开发环境，并了解项目的构建、测试和质量保障体系，为贡献代码打下坚实基础。

sentry-javascript Official Sentry SDKs for JavaScript 项目地址: https://gitcode.com/gh_mirrors/se/sentry-javascript