# @examind/ltijs-firestore 中文文档

规范地址：https://npmcn.com/package/%40examind/ltijs-firestore/

版本：2\.2\.0
npm 元数据更新时间：2024-12-17T22:06:23.713Z
中文译文更新时间：2026-11-14T03:07:11.587Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：38.7 kB，13 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2022-02-15T22:16:25.504Z
- 最新版本发布：2024-12-17T22:06:23.524Z
- 近 30 天下载量：4746（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 0 个）

## 中文简介

  
  
[![](https://raw.githubusercontent.com/Cvmcosta/ltijs/master/docs/logo-300.svg)](https://cvmcosta.github.io/ltijs)

## 安装

```sh
npm install @examind/ltijs-firestore
```

也可以使用：`pnpm add @examind/ltijs-firestore`、`yarn add @examind/ltijs-firestore`、`bun add @examind/ltijs-firestore`

## README

  
  
[![](https://raw.githubusercontent.com/Cvmcosta/ltijs/master/docs/logo-300.svg)](https://cvmcosta.github.io/ltijs)

> LTIJS Firestore 插件.

# 导言

此软件包允许 [列支敦士登](https://cvmcosta.github.io/ltijs) 去和Firestore合作 而不是和MongoDB合作.

# 安装

```
npm install @examind/ltijs-firestore
```

导入包( TypeScript 和 ES 模块):

```
import { Firestore } from '@examind/ltijs-firestore';
```

导入包( CommonJS ) :

```
const { Firestore } = require('@examind/ltijs-firestore');
```

注册插件时 [列支敦士登](https://cvmcosta.github.io/ltijs) 设置 :

```
lti.setup(
  'LTIKEY',
  { plugin: new Firestore() }
);

```

这个 `Firestore` 构造器接受具有下列属性的选项对象:

-   `collectionPrefix`: 自定义前缀,用于预置所有收藏路径。 默认为空字符串 .
    -   示例1: `ltijs-` 将创建“ ltijs- accsesstoken” 、 “ ltijs- platforms” 等收藏 .
    -   实例2: `ltijs/index/` 将创建“ ltijs/index/ accesstoken” 、 “ ltijs/index/ platforms” 等子集.

有选项的示例:

```
lti.setup(
  'LTIKEY',
  { plugin: new Firestore({collectionPrefix: 'ltijs-'}) }
);

```

## Firestore 认证

这个 `firebase-admin` 此软件包中使用的库查找一个 `LTIJS_APPLICATION_CREDENTIALS` 环境变量。 该环境变量需要指向一个GCP服务账户,可访问Firestore. 简而言之,您可以使用来自Firebase Console的Firebase Admin SDK私人密钥:

-   从 [火地控台](https://console.firebase.google.com/)
-   转到 `Project Settings` - > (中文) `Service accounts`,然后下载新的私人密钥 :

![image](https://user-images.githubusercontent.com/504505/154392946-8bb689c5-e68a-41f8-8981-862246ea4a00.png)

在某个地方保存文件(例如:. `./service-account.json`,然后点 `LTIJS_APPLICATION_CREDENTIALS` 到那个文件。 如果您使用 [多腾v](https://www.npmjs.com/package/dotenv)时,然后是您的 `.env` 文件将像这样 :

```
LTIJS_APPLICATION_CREDENTIALS=./service-account.json
```

如果您喜欢在节点.js文件中硬代码环境变量,您可以这样做:

```
process.env.LTIJS_APPLICATION_CREDENTIALS = './service-account.json'
```

注释:

-   指定 `LTIJS_APPLICATION_CREDENTIALS` 建议采用环境变量,但如果不具备, `firebase-admin` 也会寻找 `GOOGLE_APPLICATION_CREDENTIALS` 环境变量.
-   使用时 `LTIJS_APPLICATION_CREDENTIALS`,在导入前确保设置环境变量 `@examind/ltijs-firestore`。使用 dotenv 的实例 :

```
import { config } from 'dotenv';
if (process.env.NODE_ENV !== 'production') config();
import { Firestore } from '@examind/ltijs-firestore';
```

如果你无条件使用dotenv,下列方法也会起作用:

```
import 'dotenv/config';
import { Firestore } from '@examind/ltijs-firestore';
```

-   使用时 `GOOGLE_APPLICATION_CREDENTIALS`,在导入前无需设置环境变量 `@examind/ltijs-firestore`,作为 `firebase-admin` 将懒惰地装入证书。 例如,这将发挥作用:

```
import { config } from 'dotenv';
import { Firestore } from '@examind/ltijs-firestore';
if (process.env.NODE_ENV !== 'production') config();
```

-   如果在 GCP 服务器( 如 GCP 计算引擎、 GCP Cloud 函数或 GCP Cloud 运行) 内运行, 您可以省略 `LTIJS_APPLICATION_CREDENTIALS` 环境变量, 如 `GOOGLE_APPLICATION_CREDENTIALS` 将使用默认的服务账户自动设置.

## 最低特权原则

作为使用Firebase Admin SDK私人密钥的替代方案,您可以选择只授予必要的权限,以便 `@examind/ltijs-firestore`为了做到这一点, [创建自定义服务账户](https://cloud.google.com/iam/docs/creating-managing-service-accounts) 仅限 `Cloud Datastore User` 并使用其关键.

## 清理 Stale 文档

LTIJS的默认解调器提供商使用MongoDB作为其存储层,并被配置为自动去除 stale 文档. 为了在Firestore建立同样的行为,我们将使用两个策略之一,这取决于您使用的@examind/ltijs-firestore的哪个版本.

### @examind/ltijs-firestore v2+ (英语)

@ examind/litjs- firestore @ 2+ 集 `expiresAt` 关于下列文件:

-   accesstoken 密码
-   ưμ㼯a
-   点缀
-   无
-   状态

使用此字段设置 [Firestore TTL 政策](https://firebase.google.com/docs/firestore/ttl) 用于自动清理已失效的文档。 你只需要设置一次.

使用 gcloud, 将您的工程ID 替换为 {project id} 并执行以下命令 。 警告,这需要一段时间.

```
gcloud firestore fields ttls update expiresAt --collection-group=accesstoken --enable-ttl --project={project_id}
gcloud firestore fields ttls update expiresAt --collection-group=contexttoken --enable-ttl --project={project_id}
gcloud firestore fields ttls update expiresAt --collection-group=idtoken --enable-ttl --project={project_id}
gcloud firestore fields ttls update expiresAt --collection-group=nonce --enable-ttl --project={project_id}
gcloud firestore fields ttls update expiresAt --collection-group=state --enable-ttl --project={project_id}
```

为确保一切正常运行,您可以列出所有 TTL 政策 :

```
gcloud firestore fields ttls list --project={project_id}
```

#### 升级指南

当从v1.1+升级时,前作的TTL政策需要被删除,因为Firestore只允许每集组1个TTL政策. 您还要修改数据库中的现有文档, 以便包含过期的字段 .

删除以前的 TTL 政策 :

```
gcloud firestore fields ttls update age1HourAt --collection-group=accesstoken --disable-ttl --project={project_id}
gcloud firestore fields ttls update age24HoursAt --collection-group=contexttoken --disable-ttl --project={project_id}
gcloud firestore fields ttls update age24HoursAt --collection-group=idtoken --disable-ttl --project={project_id}
gcloud firestore fields ttls update age2MinutesAt --collection-group=nonce --disable-ttl --project={project_id}
gcloud firestore fields ttls update age10MinutesAt --collection-group=state --disable-ttl --project={project_id}
```

添加 `deletedAt` 至现有文档,使用firebase-admin来运行以下脚本.  
你需要设置 `GOOGLE_APPLICATION_CREDENTIALS` 用于指向此操作的 gcloud 认证密钥的环境变量 : `export GOOGLE_APPLICATION_CREDENTIALS='./my-gcloud-auth-key.json'`

```
const { initializeApp } = require('firebase-admin/app');
const { getFirestore } = require('firebase-admin/firestore');

const app = initializeApp({ projectId: 'my-project-id' });
const db = getFirestore(app);

// Set this if you're using a collection prefix
const COLLECTION_PREFIX = '';

const addMinutes = (date, minutes) =>
  new Date(date.getTime() + minutes * 60000);

(async () => {
  const collectionExpiresInMinutes = {
    accesstoken: 60,
    contexttoken: 24 * 60,
    idtoken: 24 * 60,
    nonce: 2,
    state: 10,
  };

  for (const [collection, expiresInMinutes] of Object.entries(
    collectionExpiresInMinutes,
  )) {
    const documents = await db
      .collection(`${COLLECTION_PREFIX}${collection}`)
      .get();

    for (const document of documents.docs) {
      if (!document.data().createdAt) continue;
      await document.ref.update({
        expiresAt: addMinutes(
          document.data().createdAt.toDate(),
          expiresInMinutes,
        ),
      });
    }
  }

  console.log('Done');
})();
```

### @examind/ltijs-firestore v1.1.0-v1.3.2 (英语)

@examind/litjs-firestore@1.1.0- 1.3.2 在Firestore创建的所有新文档上设置了以下字段:

-   年龄2 minutesAt
-   年龄 10
-   年龄1小时
-   24岁

使用这些字段设置 [Firestore TTL 政策](https://firebase.google.com/docs/firestore/ttl) 用于自动清理已失效的文档。 你只需要设置一次.

使用 gcloud, 将您的工程ID 替换为 {project id} 并执行以下命令 。 警告,这需要一段时间.

```
gcloud firestore fields ttls update age1HourAt --collection-group=accesstoken --enable-ttl --project={project_id}
gcloud firestore fields ttls update age24HoursAt --collection-group=contexttoken --enable-ttl --project={project_id}
gcloud firestore fields ttls update age24HoursAt --collection-group=idtoken --enable-ttl --project={project_id}
gcloud firestore fields ttls update age2MinutesAt --collection-group=nonce --enable-ttl --project={project_id}
gcloud firestore fields ttls update age10MinutesAt --collection-group=state --enable-ttl --project={project_id}
```

为确保一切正常运行,您可以列出所有 TTL 政策 :

```
gcloud firestore fields ttls list --project={project_id}
```

### @examind/ltijs-firestore #v1.0.0 (英语)

使用 [@examind/ltijs-firestore-exchedule 互联网档案馆的存檔,存档日期2013-10-02](https://www.npmjs.com/package/@examind/ltijs-firestore-scheduler)。 。 。 .

# 发展

Clone this repo, 导航到它在终端的位置并运行:

```

npm ci
npm run compile
npm link

```

在另一个项目中, 直接链接到此 repo :

```

npm link @examind/ltijs-firestore

```

## 单位测试

运行单元测试要求火地CLI(`firebase-tools`(a) 在全球安装:

```

npm install -g firebase-tools@12.4.2
npm ci
npm run compile
npm test

```

要使用 VS 代码的调试器 :

-   打开 VS 代码 `JavaScript Debug Terminal`
-   在其中添加断点 `0-provider.js` 或者说 `Firestore.ts`
-   礛 `npm test` 内部 `JavaScript Debug Terminal`

# 发布

-   套件中的 Bump 版本. json
-   `npm install`
-   提交信件 : `Release {version, e.g. 0.1.6}`

## 常见问题

### 如何安装 @examind/ltijs-firestore？

在项目目录运行 npm install @examind/ltijs-firestore，或使用 pnpm add / yarn add / bun add。

### @examind/ltijs-firestore 支持 TypeScript 吗？

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

### @examind/ltijs-firestore 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @examind/ltijs-firestore 可以商用吗？

@examind/ltijs-firestore 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @examind/ltijs-firestore 的下载量有多少？

根据 npm 官方下载统计，@examind/ltijs-firestore 在 2026/10/14 – 2026/11/12 这 30 天内被下载 4,746 次，日均约 158 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @examind/ltijs-firestore 还在维护吗？

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