名称： sentry-cli
描述： 通过 sentry-cli 使用 Sentry.io 进行错误监控。适用于处理 Sentry 版本、源映射、dSYM 文件、事件或问题管理。涵盖身份验证、版本工作流、部署跟踪和调试文件上传。

Sentry CLI

与 Sentry.io 交互，用于错误监控、版本管理和调试文件上传。

安装

# macOS
brew install sentry-cli

# npm (跨平台)
npm install -g @sentry/cli

# 直接下载
curl -sL https://sentry.io/get-cli/ | bash

身份验证

# 交互式登录 (打开浏览器)
sentry-cli login

# 或直接设置令牌
export SENTRY_AUTH_TOKEN="sntrys_..."

# 验证
sentry-cli info

将令牌存储在 .sentryclirc 或环境变量中：

[auth]
token=sntrys_...

[defaults]
org=my-org
project=my-project

版本管理

创建与完成

# 创建版本 (通常使用 git SHA 或版本号)
sentry-cli releases new "$VERSION"

# 关联提交 (将错误链接到提交记录)
sentry-cli releases set-commits "$VERSION" --auto

# 部署后标记为完成
sentry-cli releases finalize "$VERSION"

# CI 环境中的单行命令
sentry-cli releases new "$VERSION" --finalize

部署

# 将版本标记为已部署到特定环境
sentry-cli releases deploys "$VERSION" new -e production
sentry-cli releases deploys "$VERSION" new -e staging

列出版本

sentry-cli releases list
sentry-cli releases info "$VERSION"

源映射

上传源映射以解析 JavaScript 混淆错误：

# 上传所有 .js 和 .map 文件
sentry-cli sourcemaps upload ./dist --release="$VERSION"

# 指定 URL 前缀 (匹配部署路径)
sentry-cli sourcemaps upload ./dist \
  --release="$VERSION" \
  --url-prefix="~/static/js"

# 上传前验证
sentry-cli sourcemaps explain ./dist/main.js.map

注入调试 ID (推荐)

# 将调试 ID 注入源文件 (现代方法)
sentry-cli sourcemaps inject ./dist
sentry-cli sourcemaps upload ./dist --release="$VERSION"

调试文件 (iOS/Android)

dSYM 文件 (iOS)

# 从 Xcode 归档文件上传 dSYM
sentry-cli debug-files upload --include-sources path/to/dSYMs

# 从 DerivedData 目录上传
sentry-cli debug-files upload ~/Library/Developer/Xcode/DerivedData/*/Build/Products/*/*.app.dSYM

ProGuard (Android)

sentry-cli upload-proguard mapping.txt --uuid="$UUID"

检查调试文件

sentry-cli debug-files check path/to/file
sentry-cli debug-files list

事件与问题

发送测试事件

sentry-cli send-event -m "测试错误消息"
sentry-cli send-event -m "错误" --logfile /var/log/app.log

查询问题

# 列出未解决的问题
sentry-cli issues list

# 解决问题
sentry-cli issues resolve ISSUE_ID

# 静音/忽略问题
sentry-cli issues mute ISSUE_ID

监控器 (Cron)

# 包装 cron 任务
sentry-cli monitors run my-cron-monitor -- /path/to/script.sh

# 手动签到
sentry-cli monitors check-in my-monitor --status ok
sentry-cli monitors check-in my-monitor --status error

CI/CD 集成

GitHub Actions

- name: 创建 Sentry 版本
  uses: getsentry/action-release@v1
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_ORG: my-org
    SENTRY_PROJECT: my-project
  with:
    environment: production
    sourcemaps: ./dist

通用 CI

export SENTRY_AUTH_TOKEN="$SENTRY_TOKEN"
export SENTRY_ORG="my-org"
export SENTRY_PROJECT="my-project"
VERSION=$(sentry-cli releases propose-version)

sentry-cli releases new "$VERSION" --finalize
sentry-cli releases set-commits "$VERSION" --auto
sentry-cli sourcemaps upload ./dist --release="$VERSION"
sentry-cli releases deploys "$VERSION" new -e production

常用标志

故障排除

# 检查配置
sentry-cli info

# 调试上传问题
sentry-cli --log-level=debug sourcemaps upload ./dist

# 验证源映射
sentry-cli sourcemaps explain ./dist/main.js.map

# 检查连接性
sentry-cli send-event -m "test" --log-level=debug