# @firebase/crashlytics 中文文档

规范地址：https://npmcn.com/package/%40firebase/crashlytics/

版本：0\.2\.0
npm 元数据更新时间：2026-11-16T21:11:22.229Z
中文译文更新时间：2026-11-16T21:12:57.146Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40firebase/crashlytics
原文对照：https://npmcn.com/package/%40firebase/crashlytics/?lang=original
项目主页：https://github.com/firebase/firebase-js-sdk#readme
源码仓库：https://github.com/firebase/firebase-js-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.1 MB，217 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：19 个
- peer 依赖：next \>= 13\.0\.0，react \>= 16\.8\.0，@types/react \>= 16\.8\.0，@angular/core \>= 14\.0\.0，@firebase/app 0\.x，@angular/router \>= 14\.0\.0，react-router-dom \>= 6\.0\.0，@firebase/app-types 0\.x
- 首次发布：2026-05-26T23:56:14.780Z
- 最新版本发布：2026-11-16T21:11:21.983Z
- 近 30 天下载量：1315378（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

Firebase网络遥测软件包 JS SDK

## 安装

```sh
npm install @firebase/crashlytics
```

也可以使用：`pnpm add @firebase/crashlytics`、`yarn add @firebase/crashlytics`、`bun add @firebase/crashlytics`

## README

# Web Apps 的火地崩溃器 - 设置指南

> \[大 Web Apps 的崩溃程序正在使用中 **私密预览** 仅供已注册的EAP(早期访问方案)客户使用。 尚未入学的,请填写 [注册表单](https://forms.gle/FYADWGcA2k924Nqt7) 在配置应用程序之前请求访问.

并分享你的反馈!

崩溃分析 **Next.js, React, Angular, React 路由器和 TanStack 路由器应用程序** 包括客户端错误报告,去微缩堆栈痕迹,以及火地崩溃控制台的专用仪表板.

用于网络应用的Crashlytics使用Cloud Digging进行遥测存储并使用Cloud存储在引擎盖下进行源图存储,这些是付费产品,具有宽大的免费分级. 学习更多关于 [伐木定价](https://cloud.google.com/stackdriver/pricing) 财务报告和审定财务报表 [储存定价](https://cloud.google.com/storage/pricing)。 。 。 .

## 作为一个私人的预览客户,你的经验对我们团队来说是非常宝贵的. 请通过电子邮件直接向我们的团队提交错误、 API 反馈或特性请求 [崩盘- web@google.com](mailto:crashlytics-web@google.com) 或填写此选项 [反馈表单](https://forms.gle/Us8GM4YuYcYZyRNK9)。 。 。 .

## 目录

-   [代理设置提示](https://npmcn.com/package/%40firebase/crashlytics/#readme-agent-setup-prompt)
-   [步骤1:配置防火基地/云层项目](https://npmcn.com/package/%40firebase/crashlytics/#readme-step-1-configure-firebasecloud-project)
    -   [备选案文1:使用火地站(建议)](https://npmcn.com/package/%40firebase/crashlytics/#readme-option-1-using-firebase-console-recommended)
    -   [备选案文2:使用火基地CLI](https://npmcn.com/package/%40firebase/crashlytics/#readme-option-2-using-firebase-cli)
-   [第2步:核心SDK安装和初始化](https://npmcn.com/package/%40firebase/crashlytics/#readme-step-2-core-sdk-installation--initialization)
-   [第3步:框架特定设置指南](https://npmcn.com/package/%40firebase/crashlytics/#readme-step-3-framework-specific-setup-guides)
-   [步骤 4: 强制初始崩溃](https://npmcn.com/package/%40firebase/crashlytics/#readme-step-4-force-an-initial-crash)
-   [与 AI 代理调试](https://npmcn.com/package/%40firebase/crashlytics/#readme-debugging-with-ai-agents)
    -   [MCP 工具 (`crashlytics:connect`(中文(简体) )](https://npmcn.com/package/%40firebase/crashlytics/#readme-mcp-tools-crashlyticsconnect)
    -   [REST API 和 Web 浏览器元数据](https://npmcn.com/package/%40firebase/crashlytics/#readme-rest-api--web-browser-metadata)
-   [附加配置参考文件( T)](https://npmcn.com/package/%40firebase/crashlytics/#readme-additional-configuration--references)

* * *

## 代理设置提示

你可以叫你的编码代理 为你做一切! 使用下面的样本提示为您的网络应用自动设置 Crashlytics .

当您将此复制到您的编码代理中时, 请在运行前确保做到以下操作 :

1.  填写正确的 `apiKey` 财务报告和审定财务报表 `appId` 用于您的网络应用程序 `firebaseConfig`,可见于 **设置 > 常规**。 。 。 . _说明: 假设您已经用网络应用程序创建了一个 Firebase 项目 ._
2.  将您的编码代理指向 GitHub README 文件 `packages/crashlytics/`。 。 。 .

```markdown
I would like to set up the Crashlytics JS SDK to my app. My firebase app config is as follows:

const firebaseConfig = {
  apiKey: "<YOUR_FIREBASE_API_KEY>",
  authDomain: "YOUR_PROJECT_NAME.firebaseapp.com",
  projectId: "YOUR_PROJECT_NAME",
  storageBucket: "YOUR_PROJECT_NAME.firebasestorage.app",
  appId: "<YOUR_FIREBASE_APP_ID>"
};

Follow the instructions in the Firebase Crashlytics Web Setup Guide GitHub READMEs for setting up the Crashlytics Web SDK. Start with the Cloud Project Setup (using the Firebase CLI), initialize the SDK, and then follow the Setup Guide for my app’s framework to enable automatic error collection. Do not set up programmatic error capturing for this project. Replace any of the "<SOME_VARIABLE>" values in the instructions with the appropriate values based on my Firebase app config above. Also make sure to set up source map uploading for stack trace de-obfuscation. If you encounter any issues during the setup process, please ask me and I can assist you further. Ensure that you have the necessary permissions to access the Firebase project and that you have the Firebase CLI installed and configured on your machine, logged in as me (ask me to log in on your behalf).
```

* * *

## 步骤1:配置防火基地/云层项目

用于网络杠杆的崩溃分析 Google Cloud Loging, Error Reporting, 并存储在引擎盖下. 您可以使用Firebase Console(推荐)或Firebase CLI(特别是在使用编码代理时有用)自动配置您的工程.

> \[注\] 如果您来自一个已有的 Google Cloud 工程, 并且之前没有使用过 Firebase 工程, 在开始项目设置之前, 您必须接受 Firebase Console 的 Firebase 服务条款 .

### 备选案文1:使用火地站(建议)

1.  导航到 [Firebase 控制台崩溃页面](https://console.firebase.google.com/u/0/project/_/crashlytics)。 。 。 .
2.  选择您的项目 .
3.  点击 **设置** 跟着控制台的台阶走.

* * *

### 备选案文2:使用火基地CLI

如果您喜欢通过终端配置您的项目或使用AI编码代理,则运行以下命令:

```bash
firebase crashlytics:setup <YOUR_FIREBASE_APP_ID> --project <YOUR_FIREBASE_PROJECT_ID>
```

> \[注\] **先决条件**: 要求 **火基地CLI v15.34.2或以后**,所有者/编辑器项目许可,并启用了烈火计费. **认证**: 确保您得到认证并使用正确的工程:
> 
> ```bash
> firebase login
> firebase use <YOUR_FIREBASE_PROJECT_ID>
> ```
> 
> **自动设置**: 此命令自动启用所需的遥测 API(`clienttelemetry.googleapis.com`, (中文(简体) ), `firebasetelemetry.googleapis.com`, (中文(简体) ), `firebasetelemetryadmin.googleapis.com`,以及 `firebasecrashlytics.googleapis.com`,更新 API 密钥限制 `clienttelemetry.googleapis.com` (如果有限制) `firebase-telemetry` Cloud 日志桶和路由槽, 配置您的网络应用程序的遥测设置, 并选择为新问题和后退问题设置电子邮件提醒 .

* * *

## 第2步:核心SDK安装和初始化

在配置框架特定集成之前,完成核心包安装和Firebase App单通设置:

### 安装软件包

安装防火基地 JS SDK:

```bash
npm install firebase
```

### 初始化火基地 App Singleton

创建中央配置工具文件( C)`src/lib/firebase.ts`)使用在Firebase Console中发现的证书 **设置 > 常规**. 手动跟踪器和框架接口利用已初始化 `FirebaseApp` 举个例子.

```typescript
// src/lib/firebase.ts
import { initializeApp, getApps, getApp } from 'firebase/app';

const firebaseConfig = {
  apiKey: "<YOUR_FIREBASE_API_KEY>",
  authDomain: "<YOUR_AUTH_DOMAIN>",
  projectId: "<YOUR_FIREBASE_PROJECT_ID>",
  storageBucket: "<YOUR_STORAGE_BUCKET>",
  messagingSenderId: "<YOUR_MESSAGING_SENDER_ID>",
  appId: "<YOUR_FIREBASE_APP_ID>"
};

// Guarantee singleton initialization
export const app = getApps().length === 0
  ? initializeApp(firebaseConfig)
  : getApp();
```

* * *

## 第3步:框架特定设置指南

> \[大 确定你已经完成 **步骤1(配置防火基地/云层项目)** 财务报告和审定财务报表 **步骤2( 核心 SDK 安装和初始化)** 开始使用下面的框架设置指南!

选择匹配您的应用程序框架的指南 :

-   🅰️ **[角设置指南](https://npmcn.com/package/%40firebase/crashlytics/src/angular/README.md)**
-   ⚛️ **[反应设置指南](https://npmcn.com/package/%40firebase/crashlytics/src/react/README.md)**
-   🛣️ **[反应路由器设置指南](https://npmcn.com/package/%40firebase/crashlytics/src/react-router/README.md)**
-   🌼 **[TanStack 路由器设置指南](https://npmcn.com/package/%40firebase/crashlytics/src/tanstack/README.md)**
-   🔺 **[Next.js 设置指南](https://npmcn.com/package/%40firebase/crashlytics/src/next/README.md)**

* * *

## 步骤 4: 强制初始崩溃

为了验证您的设置是否有效, 并且撞车是否被妥善交付给 Firebase Crashlytics, 您可以在您的应用程序中强制进行测试崩溃 .

为确保崩溃是按要求被触发的(并且不会阻断应用程序启动或服务器侧构建失败),在您的应用程序中,在用户交互处理器(例如点击处理器或事件倾听器)中添加以下一行:

```typescript
throw new Error("Test Crash");
```

### 校验控制台的崩溃

1.  运行您的应用程序并通过执行动作(例如点击测试按钮)来触发崩溃.
2.  打开 [Firebase 控制台崩溃仪表板](https://console.firebase.google.com/u/0/project/_/crashlytics)。 。 。 .
3.  选择您查看新登录的崩溃报告的项目 .

> \[注\] 新的坠机报告可能要花几分钟时间才能出现在"火地崩溃"控制台上.

* * *

## 与 AI 代理调试

AI编码代理可以帮助在您开发环境中直接诊断和解决网络崩溃.

### MCP 工具 (`crashlytics:connect`(中文(简体) )

崩溃分析提供 [示范背景协议(MCP)](https://firebase.google.com/docs/crashlytics/ai-assistance-mcp) 工具可以让代理查询崩溃数据——包括问题、报告组、事件有效载荷和堆放痕迹——而无需手工复制.

-   **`crashlytics:connect` 提示**:一个引导性互动工作流程,该工作流程优先处理顶级问题,针对您本地代码库调查已解析的源图,并帮助代理起草修正. 学习更多在 [人工智能协助编制MCP文件](https://firebase.google.com/docs/crashlytics/ai-assistance-mcp#guided-workflow-prioritize-and-fix)。 。 。 .

### REST API 和 Web 浏览器元数据

你和你的探员也可以按程序查询 [Firebase Crashlytics RIST API 数据库崩溃分析软件](https://firebase.google.com/docs/reference/crashlytics/rest)。 。 。 .

网页出错事件及报告组曝光特定浏览器遥测维度 帮助识别平台异常:

| 外地 | 说明 | 示例 |
| --- | --- | --- |
| `browser.platform` | 客户端 OS / 平台架构 | `"macintosh"`, (中文(简体) ), `"windows"`, (中文(简体) ), `"linux"` |
| `user_agent.name` | 浏览器客户端应用程序名称 | `"chrome"`, (中文(简体) ), `"firefox"`, (中文(简体) ), `"safari"`, (中文(简体) ), `"edge"` |
| `user_agent.version` | 浏览器客户端的主要/ 小版本 | `"150"` |
| `user_agent.original` | 来自客户端请求的 Raw 用户代理字符串 | `"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."` |

* * *

## 附加配置参考文件( T)

关于高级使用选项和项目配置细节,请参考以下指南:

-   🚀 **[高级使用指南](https://npmcn.com/package/%40firebase/crashlytics/docs/ADVANCED_USAGE.md)**数字 :
    -   🏷️ **[App 版本](https://npmcn.com/package/%40firebase/crashlytics/docs/ADVANCED_USAGE.md#app-versioning)**: 设置构建脚本帮助器,用承诺散列/版本标记遥测.
    -   ⚡ **[程序配置错误](https://npmcn.com/package/%40firebase/crashlytics/docs/ADVANCED_USAGE.md#programmatic-error-capturing)**: 手动记录自定义元数据处理的例外情况.
    -   🧹 **[强制冲动](https://npmcn.com/package/%40firebase/crashlytics/docs/ADVANCED_USAGE.md#force-flushing-telemetry-records-flush)**: 卸下前立即上传队列错误遥测 .
-   ⚙️ **[配置指南](https://npmcn.com/package/%40firebase/crashlytics/docs/CONFIGURATION.md)**数字 :
    -   🔔 **[警报](https://npmcn.com/package/%40firebase/crashlytics/docs/CONFIGURATION.md#alerting)**:通过Firebase Console或CLI来配置针对新问题和后退问题的电子邮件提醒,或设置高级云监测提醒.
    -   🎚️ **[取样](https://npmcn.com/package/%40firebase/crashlytics/docs/CONFIGURATION.md#sampling)**: 使用Admin API或Cloud Logging排除过滤器控制遥测体积和成本.
    -   ⚙️ **[启用/ 失效的遥测收藏](https://npmcn.com/package/%40firebase/crashlytics/docs/CONFIGURATION.md#enabledisable-telemetry-collection)**: 程序上打开或关闭遥测集.
    -   📋 **[日志外观](https://npmcn.com/package/%40firebase/crashlytics/docs/CONFIGURATION.md#log-schema)**:遥测日志场和有效载荷结构的充分参考.

## 常见问题

### @firebase/crashlytics 是什么？

Firebase网络遥测软件包 JS SDK

### 如何安装 @firebase/crashlytics？

在项目目录运行 npm install @firebase/crashlytics，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@firebase/app（0\.x）、@firebase/app-types（0\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 crashlytics-setconstants，可以用 npx crashlytics-setconstants 直接运行。

### @firebase/crashlytics 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @firebase/crashlytics 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @firebase/crashlytics 可以商用吗？

@firebase/crashlytics 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @firebase/crashlytics 的下载量有多少？

根据 npm 官方下载统计，@firebase/crashlytics 在 2026/10/15 – 2026/11/13 这 30 天内被下载 1,315,378 次，日均约 43,846 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @firebase/crashlytics 还在维护吗？

最新版本 0\.2\.0 发布于 2026/11/17（今天）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/05/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

