# @alienplatform/bindings 中文文档

规范地址：https://npmcn.com/package/%40alienplatform/bindings/

版本：3\.3\.54
npm 元数据更新时间：2026-11-05T10:26:35.945Z
中文译文更新时间：2026-11-05T20:28:36.362Z
软件包许可：FSL-1\.1-Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40alienplatform/bindings
原文对照：https://npmcn.com/package/%40alienplatform/bindings/?lang=original
项目主页：https://alien.dev/
源码仓库：https://github.com/alienplatform/alien

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

- 包体积（解压后）：290 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-03-14T15:27:14.277Z
- 最新版本发布：2026-11-05T10:26:35.776Z
- 近 30 天下载量：28219（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：71（近 12 个月 71 个）

## 中文简介

用于异形存储、 kv、 队列、 金库、 和邮资的直线类型脚本绑定

## 安装

```sh
npm install @alienplatform/bindings
```

也可以使用：`pnpm add @alienplatform/bindings`、`yarn add @alienplatform/bindings`、`bun add @alienplatform/bindings`

## README

# `@alienplatform/bindings`

用于外星存储、 kv、 队列、 金库、 链接- 容器的直接类型脚本绑定 和Postgres over a 正在处理 [美洲狮](https://napi.rs/) 塞顿。 外加者自己住在罗斯特 条框 `crates/alien-bindings-node`; 此软件包是已发布的 JavaScript 把它包起来.

## 远程存储

使用 `Bindings.forRemoteDeployment` 从信任的后端访问存储器 用于现有部署的资源。 永远不要在浏览器中放出异形 API 令牌, 移动,或其他客户端代码。 符号必须具有写入权限 部署; 仅读符号不能解决云证书.

```ts
import { Bindings } from "@alienplatform/bindings"

const bindings = await Bindings.forRemoteDeployment({
  deploymentId: process.env.ALIEN_DEPLOYMENT_ID!,
  token: process.env.ALIEN_API_TOKEN!,
})

const archive = bindings.storage("archive")
const write = await archive.put("reports/latest.json", Buffer.from(JSON.stringify({ ready: true })), {
  condition: "absent",
  attributes: {
    contentType: "application/json",
    cacheControl: "private, max-age=60",
    metadata: { schema: "report-v1" },
  },
})

const head = await archive.head("reports/latest.json")
const object = await archive.get("reports/latest.json")
const report = JSON.parse(object.data.toString())
console.log(write.eTag, head.meta, head.attributes, report)
const reports = await archive.list("reports/")

await archive.delete("reports/latest.json")
```

云存储提供者坚持这些对象属性. 本地文件系统 提供者拒绝带有属性的写作,因为它不能代表它们. GCS 也拒绝 `contentEncoding: "gzip"`: 它的减压转码省略 字节精确所需的响应长度 。 其他GCS编码,例如 `br`被保存下来.

`condition: "absent"` 制造 `put` 仅用原子创建写入。 如果对象 已存在, 操作失败 `STORAGE_OBJECT_ALREADY_EXISTS` 而不是替换它.

远程存储曝光 `get`, (中文(简体) ), `put`, (中文(简体) ), `head`, (中文(简体) ), `list`,以及 `delete`它不会 曝光复制或签名的 URL 。 一样 `Bindings` 和存储手柄仍然有效 本地客户端刷新短寿命的云层证书并定期更新 重新发现部署的指定管理器. 旋转外星 API 令牌 需要新建 `Bindings` 数值。 过 `apiBaseUrl` 仅在 针对非默认的异构 API 端点; 普通 HTTP 只在 a 上被接受 地方发展的回放地址.

命名的资源必须是跑道、 冻结 S3、 GCS 或 Azure Blob 存储器 已启用远程访问资源。 允许远程访问增加了混凝土 对象读取/写入/列表/删除该桶或容器的访问权限 部署的专用遥控器身份。 生成并应用更新客户设置 允许它在现有部署中。 终点返回一个短暂的租约 对于远程绑定身份,只有在它验证了指定的资源之后,所以 外国代币和所有退回的供应商证书必须作为后端处理 秘密,我们有秘密.

## 远程 KV

信任的后端可以使用相同的读取和写入客户端的 KV 资源 短期证书租赁作为远程存储:

```ts
const bindings = await Bindings.forRemoteCustomer({ project, externalId, token })
await bindings.kv("check-cache").setJson("status", { ready: true }, { ttl: 86400 })
```

启用 `remoteAccess` 并首先应用更新的设置. 资源必须运行和冻结。 AWS 允许在 选定的 DynamomDB 表格; Azure 授予选定表格上的实体操作. Firestore IAM 无法在共享默认数据库中隔离收藏, 因此它的 远程身份可以在整个项目中访问文件。 仅启用 当范围合适时.

远程 KV 使用相同的读取、 写入、 有条件写入、 扫描和逻辑 TTL 行为作为工作量 KV. 原始值限制在DynamoDB上的408 576字节, Firestore上的783,360字节(基础编码加文件元数据需要室), 和24,576字节在Azure和本地存储. DynamoDB 保留它的一基B 400 KiB 密钥和元数据项限制 。 使用对象存储值较大 .

## 链接集装箱

这些工厂由下列公司再出口: `@alienplatform/sdk` 为工人应用. 长期运行的Control和守护进程应用程序可以直接导入此包. A 类 链接容器为只读服务发现 :

```ts
import { container } from "@alienplatform/bindings"

const database = container("database")
const internalUrl = await database.getInternalUrl()
const publicUrl = await database.getPublicUrl() // string | null
```

使用内部 URL 调用同一部署中的资源 。 使用 只有当呼叫者不在私人网络时, 才会公开 URL .

## 邮资

Postgres是只连接:每个后端都说相同的线程,所以 绑定手背连接细节, 您的应用程序与自己的驱动程序连接 . 解析管理下云后端( Aurora, Cloud SQL, 灵活服务器) 读取 该云的秘密商店的密码 使用工作量本身的身份—— 只能装上定位器.

```ts
import { Client } from "pg"
import { postgres } from "@alienplatform/bindings"

const conn = await postgres("my-db").connection()

// Field style: node-postgres parses a URL's sslmode and would override `ssl`, so
// pass the fields when you need `conn.ssl` to take effect.
const client = new Client({
  host: conn.host,
  port: conn.port,
  database: conn.database,
  user: conn.username,
  password: conn.password,
  ssl: conn.ssl,
})
await client.connect()
```

`conn.connectionString` 与a `postgres://` URL,带 证书%-编码, 对于驾驶员谁需要一个.

外部 (BYO) Postgres 绑定默认使用已验证的TLS. 他们 `sslMode` 政策被故意限制在 `"verify-full"` 财务报告和审定财务报表 `"disable"` 因为 节点不能代表 libpq 的机会性 `prefer` 后退无 拥有连接尝试 。 使用 `"disable"` 仅作为明确的相容性 选择退出纯文本服务器; 缺少遗留配置默认为 `"verify-full"`。 。 。 .

## 原生添加分辨率

导入软件包从不加载附加件, 因此软件包仍然保留 `sideEffects: false`环保工厂把它装入第一个装入 操作. `Bindings.forRemoteDeployment` 立即装入, 因为管理器 发现是合成器的一部分. `src/loader.ts` 解决它 顺序 :

1.  `ALIEN_BINDINGS_ADDON_PATH` - 一条通往 `.node` 文档。 Dev/测试 只能逃出舱口;从未设置在已公布的安装中.
2.  每个平台的预建包 `@alienplatform/bindings-<triple>`,拉动 作为 `optionalDependency`。这就是终端用户如何获得加词: `npm`编号 :`bun` 只安装匹配主机的软件包 `os`编号 :`cpu`编号 :`libc`编辑 `optionalDependencies` 块已存在 **只见于已公布的清单** - 没错 发布时由发布管道注入,所以工作空间检查 携带无.
3.  倒计时: 本地建起的加通 `crates/alien-bindings-node/alien-bindings-node.<triple>.node`时 从安装的软件包走过来。 仅在装入时 `version()` 匹配 此软件包的版本( stale building 警告并拒绝).

## 地方发展

为主机构建附加符一次, 然后运行任何导入包的操作 :

```sh
bun run build:addon   # or: pnpm -C packages/bindings run build:addon
```

`build:addon` 运行 `napi build --platform --release` 反对 `crates/alien-bindings-node` 并放弃 `.node` 旁边的箱子,在哪里 加载器的dev倒置后(上第3步)发现. 更改任何 Rust 后重建 内 `alien-bindings` 或者说 `alien-bindings-node`。构建 `.node` 被点燃了. `build:addon` 仅用于主机 三进制; 在一个Mac上, 横跨 其他 mac 三进制(例如. `darwin-x64` 从一个 `arm64` 需要明确 `napi build --release --target x86_64-apple-darwin --cwd ../../crates/alien-bindings-node`。 。 。 .

将装载器指向另一个地方,设定 `ALIEN_BINDINGS_ADDON_PATH` 走向其道路(步骤1).

## 预建软件包( E)`npm/`(中文(简体) )

`npm/<triple>/` 持有每个平台软件包的骨架 (单位:千美元)`darwin-arm64`, (中文(简体) ), `darwin-x64`, (中文(简体) ), `linux-x64-gnu`, (中文(简体) ), `linux-arm64-gnu`) (中文(简体) ). 每个载体 (单位:千美元) `package.json` (单位:千美元)`name`编号 :`os`编号 :`cpu`编号 :`libc`编号 :`main`编号 :`files`和一个读取器 `.node` 是在建设时间开始的 从来没有承诺过 没有木丝 目标:部署基础图像是glibc(链卫/wolfi-base),而不是高山.

释放管道在原生跑道上制造出每个加成物,分级进入 匹配 `npm/<triple>/` dir, 重写占位符 `0.0.0` 给 释放版本, 注入精确版本 `optionalDependencies` 输入此选项 软件包已公布清单,并在 包装 固定准确的版本只保证出版的包装 永远装入匹配版本平台加载.

### 队列批次

`queue("events").sendBatch([{ order: 1 }, { order: 2 }])` 发送 JSON 消息; `sendBatchText(["first", "second"])` 发送文本。 Python 曝光时 `send_batch` 财务报告和审定财务报表 `send_batch_text` 在队列控件上。 粗糙的暴露 `Queue::send_batch` 财务报告和审定财务报表 `BoundQueue::send_batch`。 。 。 .

每种输入按输入顺序返回一个结果: `sent` 指提供者 确认接受, `rejected` 包含一个代码和信件,用于确定 拒绝,和 `unknown` 在无法发送时包含代码和信件 已经建立。 重试未知结果可产生重复. 没有 跨批自动重复或交易担保。 之前的一个例外 结果返回意味着没有试图发送.

信件在序列化后必须包含1–65,536个UTF-8字节. 请求是 使用 SQS SendMessageBatch(最多10个条目和256KiB)进行块化,Pub/Sub发布, 并发送服务巴士HTTP批次。 服务 公共汽车还计算了JSON信封/逃逸 反对256KiB批量限制,因此严重逃逸的文本可能被否决. 空输入 返回空结果。 现有范围出版许可覆盖分批.

### 远程队列

发布冻结队列 `remoteAccess: true`,应用其最新设置 从后端解决它:

```ts
const bindings = await Bindings.forRemoteCustomer({ project, externalId, token })
const events = bindings.queue("events")
await events.send({ order: 1 })
const results = await events.sendBatch([{ order: 2 }, { order: 3 }])
```

Python 用途 `await Bindings.for_remote_customer(...)`,则 `bindings.queue("events").send(...)` 或者说 `.send_batch(...)`两种语言都使用 Rust 供应商执行。 TypeScript 和 Python 远程队列控件只曝光发送; 云许可也拒绝接收、承认和清洗。 全权证书 由于租约到期,在运营前更新。 SQS、Pub/Sub和服务巴士 使用资源范围出版社赠款。 批次结果有相同的部分失败 语义作为本地队列手柄 .

新会话的沙盒能力来自 `await sandbox.capabilities()`。 。 。 . 重新连接后, 使用 `await sandbox.capabilities(sandboxId)` 以查询 届会。 Azure会议保留其原有的本地或代理运输工具 图像升级和回滚,所以工作支持可以与新会话不同.

## 常见问题

### @alienplatform/bindings 是什么？

用于异形存储、 kv、 队列、 金库、 和邮资的直线类型脚本绑定

### 如何安装 @alienplatform/bindings？

在项目目录运行 npm install @alienplatform/bindings，或使用 pnpm add / yarn add / bun add。

### @alienplatform/bindings 支持 TypeScript 吗？

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

### @alienplatform/bindings 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @alienplatform/bindings 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @alienplatform/bindings 可以商用吗？

@alienplatform/bindings 使用 FSL-1\.1-Apache-2\.0 许可。声明的许可为 FSL-1\.1-Apache-2\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @alienplatform/bindings 的下载量有多少？

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

### @alienplatform/bindings 还在维护吗？

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