跳转到内容
FortressFlag Docs

Node.js 快速入门

几分钟之内，你的 Node 服务就会在进程内评估 feature flags——每次检查没有网络跳转，请求路径上没有延迟，一次轮询服务你的进程处理的每一个请求。

零运行时依赖：这个包的 dependencies 块根本不存在，而且会一直如此。

1. 安装

Section titled “1. 安装”

SDK 放在 GitHub 上的一个公开仓库里——直接从那里安装，并固定到发布版本：

Terminal window
npm install github:FortressFlag/FortressFlag_SDK_node#v1.0.0

省略 #v1.0.0 就会改为跟踪 development 分支——试一个修复时很方便，但不是你在生产环境想要的。

这个包是纯 ESM 的。在 Node 22 及更高版本上，CommonJS 代码也可以用一句普通的 require("@fortressflag/sdk-node") 加载它。

2. 服务器密钥——真正的机密

Section titled “2. 服务器密钥——真正的机密”

这个 SDK 使用服务器密钥（ffs_…），它和移动端与 Web SDK 所携带的客户端密钥恰恰相反：它可以下载你的完整 ruleset，包括定向规则。像对待数据库密码一样对待它——环境变量或机密管理器，绝不进代码，绝不进仓库，绝不进日志。两类密钥，并排对照。

3. 启动客户端

Section titled “3. 启动客户端”
import { create } from "@fortressflag/sdk-node";


let client;
try {
  client = create({ key: process.env.FF_SERVER_KEY });
} catch (error) {
  // SDK 唯一会抛出的地方：密钥格式错误，在任何东西开始提供之前。
  console.error(error);
  process.exit(1);
}


await client.start(AbortSignal.timeout(15_000)); // 在第一个 ruleset 到达时 resolve（或到达截止时间）


// ... 你的服务运行；flag 检查现在是内存中的函数调用。

start 永远不会 reject——如果第一次获取不能及时完成，客户端会在后台继续尝试，而你的调用方在此期间拿到它们的回退值。而且轮询器永远不会让你的进程一直活着：当你的代码结束时，Node 像平常一样退出。

4. 评估一个 flag

Section titled “4. 评估一个 flag”
const enabled = client.bool(
  "new-checkout",
  {
    key: "user-42", // 你的稳定上下文 key：用户 id、会话 id——由你选择
    tags: { cohort: "beta" },
  },
  false, // flag 未知或从未获取到任何东西时的回退值
);

client.string 和 client.number 的用法相同。上下文 key 是百分比灰度用来分桶的东西——始终传入同一个标识符，每个用户就会得到一个稳定的分组。它是你的数据：SDK 从不验证、存储或记录它。

就是这样——你的服务正在本地评估 flag。一次控制台变更会在大约一分钟内到达每一个进程。

评估永远不会失败

Section titled “评估永远不会失败”

bool、string 和 number 总会给出答案，从不抛出——一个 flag 方面的问题绝不能拖垮你的服务。重启后的进程在第一次获取完成之前提供你调用处的回退值（或者在配置里设置 cachePath，把最后一个 ruleset 持久化到你选定的文件，重启就能立即从它恢复）。即使密钥被吊销也不会弄坏任何东西：SDK 会继续用它最后下载的 ruleset 评估，直到你交给它一个新密钥。

接下来去哪

Section titled “接下来去哪”