@getalby/bitcoin-connect

中文文档
3.12.3发布于 2026/05/23MITTypeScriptESM + CJS近 30 天下载 1.1万

用WebLN连接到闪电钱包和为网站提供动力的Web组件

中文使用文档
文档目录44 节
  1. 试试看
  2. 移徙指南
  3. QQ 快速启动
  4. 反应软件包
  5. Web 组件软件包
  6. HTML (CDN) (中文(简体) )
  7. 使用量
  8. 纯JS
  9. 反应
  10. 其他框架
  11. 纯 HTML
  12. 比特币连接 API
  13. WebLN 全球对象
  14. 样式
  15. 字体
  16. 黑暗模式
  17. 接触基本供应商(NWC、LNC等)
  18. 演示文稿
  19. 纯 HTML 演示
  20. 反应演示
  21. 更多演示
  22. 发展
  23. 安装
  24. 运行虚拟
  25. 其他 dev 选项
  26. 生产建设
  27. 测试
  28. 需要帮忙吗?
  29. 财务问题
  30. 怎么会这样?
  31. 这是否适用于移动浏览器和移动PWA,还是没有WebLN扩展的桌面浏览器?
  32. 它是否与桌面扩展功能相通 ?
  33. 我可以把它连接到我的手机钱包吗?
  34. 一个用户能连接任何闪电钱包吗 ?
  35. 如果用户离开页面或关闭浏览器,它是否"记得"?
  36. 安全吗?
  37. 为了把这个添加到网站,我需要做什么?
  38. 支持什么连接器 ?
  39. 如果用户用另一个钱包支付, 为什么模式会保持开放 ?
  40. 为什么是窗户。 连接后未设置 ?
  41. 为什么Bitcoin Connect在一些页面上不起作用?
  42. 已知问题
  43. 🔥 立特
  44. 许可证

image

比特币连接

该项目包括连接到闪电钱包和启用的网络组件 网络LN. 网站只需与WebLN接口即可与多个钱包连接,就像Alby扩展. 然而,不需要安装扩展-Bitcoin Connection由网站提供. 用户可以同时从桌面和移动设备连接,使用他们最喜欢的浏览器. PWAs (美国) 只是工作时. Bitcoin Connect的组件与纯HTML和所有的Javascript库或框架相配合,如React,Angular,Vue,Solid.js等.

Bitcoin Connect也支持良好的发票付款UI, 接受单行码的付款.

QQ Bitcoin Connect于2023年12月17日赢得了"BOLT FUN Legends of Lightning vol.2"黑客赛事.

比特币连通公司有些钱可以买礼物 如果您想提供新功能或向受欢迎的网络应用程序添加比特币连接, 请联系 你好@ getalby.com。 。 。 .

试试看

演示

移徙指南

有多个分解变化 页:1. 见我们的移徙指南 这里单击 这里 为v2.

QQ 快速启动

这个软件包目前位于阿尔法. 它有惊人的特性, 但它正在使用 协议的新特性 比如WebLN和NWC 还没有定稿, 并且可能 打破更改或错误.

反应软件包

npm install @getalby/bitcoin-connect-react 或者说 yarn add @getalby/bitcoin-connect-react

Web 组件软件包

npm install @getalby/bitcoin-connect 或者说 yarn add @getalby/bitcoin-connect

HTML (CDN) (中文(简体) )

您可以在没有任何构建工具的情况下使用 Bitcoin 连接 :

<script type="module">
  import {launchModal} from 'https://esm.sh/@getalby/bitcoin-connect@^3.12.2'; // jsdelivr.net, skypack.dev also work

  // use Bitcoin connect API normally...
  launchModal();

  // or if you just want access to the web components:
  import 'https://esm.sh/@getalby/bitcoin-connect@^3.12.2';
</script>

<!-- Bitcoin Connect components are now available -->
<bc-button></bc-button>

使用量

纯JS

import {
  init,
  launchModal,
  launchPaymentModal,
  requestProvider,
} from '@getalby/bitcoin-connect';

// Initialize Bitcoin Connect
init({
  appName: 'My Lightning App', // your app name
});

// launch modal programmatically
await launchModal();

// launch modal to receive a payment
await launchPaymentModal({
  invoice: 'lnbc...',
  onPaid: ({preimage}) => alert('Paid: ' + preimage), // NOTE: only fired if paid with WebLN - see full api documentation below
});

// or request a WebLN provider to use the full WebLN API
const weblnProvider = await requestProvider();
const {preimage} = await weblnProvider.sendPayment('lnbc...');

继续往下走 整个比特币连接API.

反应

import {Button, PayButton, init, launchModal, launchPaymentModal, closeModal, requestProvider, Connect, SendPayment} from '@getalby/bitcoin-connect-react';

// Initialize Bitcoin Connect
init({
  appName: "My Lightning App", // your app name
})

// render the Bitcoin Connect button
<Button onConnect={(provider) => {
  const {preimage} = await provider.sendPayment("lnbc...");
}}/>

// render a "Pay Now" button
// invoice can be unset initially - using the onClick function is a good time to fetch the invoice
// set the `payment` prop to override the payment status if a payment was made externally
<PayButton invoice={invoice} onClick={() => {
  invoice = fetchInvoice();
  setInvoice(invoice)
}} onPaid={(response) => alert("Paid! " + response.preimage)} payment={{preimage: 'my-preimage'}}/>

// render the connect flow on its own without the modal
<Connect/>

// render the send payment flow on its own without the modal (for E-Commerce flows)
// set the `payment` prop to override the payment status if a payment was made externally
<Payment invoice="lnbc..." onPaid={(response) => alert("Paid! " + response.preimage)} payment={{preimage: 'my-preimage'}}/>

// request a provider
<button onClick={() => {
  // if no WebLN provider exists, it will launch the modal
  const weblnProvider = await requestProvider();
  const { preimage } = await weblnProvider.sendPayment("lnbc...")
}}>
  Request WebLN provider
</button>

// open modal programmatically to connect a wallet
<button onClick={() => launchModal()}>
  Programmatically launch modal
</button>

// open modal programmatically to pay an invoice (for one-off payments)
<button onClick={() => launchPaymentModal({invoice: "lnbc...", onPaid: ({preimage}) => alert("Paid: " + preimage)})}>
  Programmatically launch payment modal
</button>

// close modal programmatically
closeModal();

下一个联合战略/安全部门改革

确保只导入和制取组件 客户端。可以通过使用下个/动力学与 ssr: false (并在使用下JS应用程序路由器时添加"使用客户端"指令),或者动态导入等.

"use client"
import dynamic from 'next/dynamic';
const Button = dynamic(
  () => import('@getalby/bitcoin-connect-react').then((mod) => mod.Button),
  {
    ssr: false,
  }
);

// Render the Button normally

<Button />

// or to use the API:

<button
  onClick={async () => {
    const launchModal = await import('@getalby/bitcoin-connect-react').then(
      (mod) => mod.launchModal
    );
    launchModal();
  }}
>
  Launch modal
</button>

// to set the global webln object:

useEffect(() => {
  // init bitcoin connect to provide webln
  const {onConnected} = await import('@getalby/bitcoin-connect-react').then(
    (mod) => mod.onConnected
  );
  const unsub = onConnected((provider) => {
    window.webln = provider;
  });

  return () => {
    unsub();
  };
}, []);

见 下一个 JS 财务报告和审定财务报表 下一个 JS 遗产 完整示例的演示.

其他框架

QQ 核心 Bitcoin Connect 包在所有框架上工作,因为它由网络组件提供动力. 然而,包装可以简化比特币连接的使用.

用另一个流行的框架? 请让我们知道,或觉得自由 创建公关为包装。 执行实例见“反应包”.

纯 HTML

构成部分

比特币连接(Bitcoin Connect)为允许用户连接所期望的闪电钱包而暴露出以下的网络组件:

  • <bc-button/> - 点击启动比特币连接模式
    • 参数 :
      • title - (可选)更改按钮的标题
  • <bc-pay-button/> - 点击启动比特币连接支付模式
    • 参数 :
      • invoice - BOLT11发票 只要开出发票 Modal 才会打开
      • payment-methods (可选)"全""外""内"
      • title - (可选)更改按钮的标题
      • preimage - (可选) 如果您收到外部付款, 设置此选项
    • 活动 :
      • click - 点击按钮时开火。 您可以在此装入一张发票并按下按钮 setAttribute('invoice', 'lnbc...') 然后自动启动模式
      • bc:onpaid - 火灾事件,WebLN付款反应 event.detail (内装) preimage(中文(简体) )
  • <bc-connect/> - 无模式地渲染连接钱包
  • <bc-payment/> - 无模式地提出付款请求
    • 参数 :
      • invoice - BOLT11发票
      • payment-methods (可选)"全""外""内"
      • paid - 说吧 实验 设定为真实,以标记外部付款(将改为 preimage 页:1
    • 活动 :
      • bc:onpaid - 火灾事件,WebLN付款反应 event.detail (内装) preimage(中文(简体) )

比特币连接 API

初始化比特币连接

import {init} from '@getalby/bitcoin-connect-react';

// Initialize Bitcoin Connect
init({
  appName: 'My Lightning App', // your app name
  // filters: ["nwc"],
  // showBalance: true,
  // persistConnection: true, // if false, connection will not be saved to local storage
  // providerConfig: {
  //   nwc: {
  //     authorizationUrlOptions: {
  //       requestMethods: ['get_balance', 'make_invoice', 'lookup_invoice'],
  //     },
  //   },
  // }
});
  • appName - 请求访问钱包的应用程序名称。 目前用于NWC连接(例如Alby Hub)
  • filters - 过滤要显示的连接器类型。 示例:"nwc"(只显示NWC连接器).
  • showBalance - 如果错误, 请不要要求连接的钱包余额
  • autoConnect - 如果错误,在页面加载时防止自动连接到用户的NWC钱包. NWC 连接 URL 作为散列传递 nwc 参数(URL编码). 示例 https://myapp.com/#/?nwc=nostr%2Bwalletconnect%3A%2F%2F...
  • providerConfig - 说吧 实验: 添加提供商专用配置(针对NWC,LNC,LNbits等). 目前仅 nwc.authorizationUrlOptions 被支持. NWCAuthorizationUrlOptions 可见于 阿尔比 JS SDK。 。 。 .

请求提供者

有了一行代码,你就可以确保你有一个WebLN供应商,并准备使用. 如果没有,将启动比特币连接模式。 应当要求用户进行互动,以避免向用户意外显示模式.

import {requestProvider} from '@getalby/bitcoin-connect';

const provider = await requestProvider();
await provider.sendPayment('lnbc...');

程序启动模式

然后,可通过以下方式推出该模式:

import {launchModal} from '@getalby/bitcoin-connect';

launchModal(); // A `<bc-modal/>` element will be injected into the DOM

按程序启动收款模式

要收到付款,可按程序以下列方式打开:

import {launchPaymentModal} from '@getalby/bitcoin-connect';

const {setPaid} = launchPaymentModal({
  invoice: 'lnbc...',
  //paymentMethods: "all" // "all" | "external" | "internal"
  onPaid: (response) => {
    clearInterval(checkPaymentInterval);
    alert('Received payment! ' + response.preimage);
  },
  onCancelled: () => {
    clearInterval(checkPaymentInterval);
    alert('Payment cancelled');
  },
});

// below is an example of LNURL-verify from https://github.com/getAlby/js-lightning-tools
// you can write your own polling function to check if your invoice has been paid
// and then call the `setPaid` function.
const checkPaymentInterval = setInterval(async () => {
  // Make sure your verifyPayment function ONLY verifies the payment.
  // If there are any side effects they will only happen when the payment is made externally.
  const paid = await invoice.verifyPayment();

  if (paid && invoice.preimage) {
    setPaid({
      preimage: invoice.preimage,
    });
  }
}, 1000);

注:对于外部支付的P2P付款,Bitcoin Connect无法知道何时付款. launchPaymentModal 更适合简化电子商业用例,您可以亲自检查发票.

程序上关闭模式

import {closeModal} from '@getalby/bitcoin-connect';

closeModal();

连接到用户钱包

import {connect} from '@getalby/bitcoin-connect';

connect({
  connectorName: 'NWC',
  connectorType: 'nwc.generic',
  nwcUrl: 'nostr+walletconnect://...',
});

连接到用户的 NWC 钱包

import {connectNWC} from '@getalby/bitcoin-connect';

connectNWC('nostr+walletconnect://...');

从钱包断开连接

import {disconnect} from '@getalby/bitcoin-connect';

disconnect();

获取连接符配置

返回当前连接连接器的已保存配置( 如果已连接)

import {getConnectorConfig} from '@getalby/bitcoin-connect';

const connectorConfig = getConnectorConfig();
if (connectorConfig) {
  // can now access e.g. connectorConfig.connectorName
}

刷新余额

程序上为所有人启动平衡刷新 <bc-balance> 组件。 用于支付或收到资金后更新显示的余额.

import {refreshBalance} from '@getalby/bitcoin-connect';

refreshBalance();

活动

已连接

当提供WebLN供应商时,这一事件就会起火.

  • 当用户第一次连接时
  • 用户先前已连接时在页面上重新加载
import {onConnected} from '@getalby/bitcoin-connect';

const unsub = onConnected(async (provider) => {
  const {preimage} = await provider.sendPayment('lnbc...');
});
unsub();
连接

当一个WebLN提供商在初始化时,这个事件会起火.

  • 当用户第一次连接时
  • 用户先前已连接时在页面上重新加载
import {onConnecting} from '@getalby/bitcoin-connect';

const unsub = onConnecting(async () => {
  // do something...
});
unsub();
已断开

当用户手动断开比特币连接时,此事件会起火.

import {onDisconnected} from '@getalby/bitcoin-connect';

const unsub = onDisconnected(async () => {
  // do something...
});
unsub();
已打开

此事件会在比特币连接模式打开时起火.

import {onModalOpened} from '@getalby/bitcoin-connect';

const unsub = onModalOpened(async () => {
  // do something...
});
unsub();
在 Modal Closed 上关闭

此事件在比特币连接模式关闭时会起火.

import {onModalClosed} from '@getalby/bitcoin-connect';

const unsub = onModalClosed(async () => {
  // do something...
});
unsub();

WebLN 全球对象

警告:webln 默认不再被注入到窗口对象中. 如果你需要这个,你还必须通过断开来清除它。 比特币连接不拥有 window.webln 一旦你指定了它,所以一个断开的钱包仍然可以通过被保存的全局到达,直到被移除为止. 对 onConnected 与 onDisconnected数字 :

import {onConnected, onDisconnected} from '@getalby/bitcoin-connect';

onConnected((provider) => {
  window.webln = provider;
});
onDisconnected(() => {
  delete window.webln;
});

没有 onDisconnected 清理,你的应用程序还可以打电话 window.webln.sendPayment() 在用户点击断开连接后.

很快会有更多方法 你需要什么吗? 告诉我们!

样式

这些变量必须设置在根上或包装任何比特币连接组件的容器元素上.

html {
  --bc-color-brand: #196ce7;
  --bc-color-brand-dark: #3994ff; /* use a different brand color in dark mode */
  --bc-brand-mix: 100%; /* how much to mix the brand color with default foreground color */
  --bc-color-brand-button-text: #ffffff; /* override text color for primary button. Normally this is based on the luminance of the brand color */
  --bc-color-brand-button-text-dark: #ffffff; /* override text color for primary button in dark mode. Normally this is based on the luminance of the brand color in dark mode */
}

使用近白或黑色的品牌颜色? 或设置下调 bc-brand-mix 或确保使用非白色的 bc-color-brand 并关闭为 bc-color-brand-dark 以避免与模式背景颜色相冲突.

字体

默认Bitcoin Connect不会使用自定义字体来减少脚印和隐私,但可以通过提供CSS来使用自定义字体 Inter (sans serif) 和 (英语) Roboto Mono (莫诺空间)家庭。 例如,在您的 HTML 标题中:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
  rel="stylesheet"
/>
<link
  href="https://fonts.googleapis.com/css2?family=Roboto Mono:wght@400;500;600;700&display=swap"
  rel="stylesheet"
/>

黑暗模式

比特币连接使用 prefers-color-scheme 以自动检测光/暗模式.

手动

如果您的站点使用手动主题切换器, 您可以通过这些步骤强制一个主题 :

参见示例 这里

  1. 设定 globalThis.bcDarkMode = "class" 在此之前 任何比特币连接组件都会被渲染
  2. "dark" 必须作为类名添加到文档中才能启用暗模式(例如). <html class="dark"> 或者说 document.documentElement.classList.add('dark')否则将强制使用光模式.

接触基本供应商(NWC、LNC等)

说明: WebLN 类型 类型定义需要.

import { WebLNProviders, requestProvider } from "@getalby/bitcoin-connect";

const provider = await requestProvider();

if (provider instanceof WebLNProviders.NostrWebLNProvider) {
  provider.client.nostrWalletConnectUrl;
}

if (provider instanceof WebLNProviders.LNCWebLNProvider) {
  provider.lnc.lnd.lightning.listInvoices(...);
}

if (provider instanceof WebLNProviders.LnbitsWebLNProvider) {
  provider.requestLnbits('GET', '/api/v1/wallet');
}

演示文稿

纯 HTML 演示

见 纯 HTML

示例代码

更完整的例子是: dev/vite/index.html 页面存档备份,存于互联网档案馆 可以通过遵循以下开发指令来操作.

反应演示

见 反应

示例重现

支付闪电地址的发票

支付电子商务

NextJS (App 路由器)

见 下一个 JS

下个JS 后遗症( 文件目录)

见 下一个 JS 遗产

更多演示

打开 演示

发展

安装

运行 yarn install && (cd dev/vite && yarn install)

运行虚拟

运行 yarn dev

其他 dev 选项

打开 备忘

生产建设

yarn build

测试

yarn test

需要帮忙吗?

我们乐于提供帮助,请与我们联系或制造问题.

财务问题

怎么会这样?

比特币连接(Bitcoin Connect)为用户提供多个选项来连接到闪电钱包,每个选项都与WebLN兼容. 任何已经存在的WebLN供应商(如Alby这样的已安装的WebLN扩展)都会被发现和提供,以及通过NWC等协议建立新的WebLN供应商的选项. 无论您选择哪一个选项, WebLN 提供商将会可供网站与您的闪电钱包交互使用. 类似于Alby扩展,新选项(称为Connectors)可以很容易地被添加,因为它们都遵循一个共同的,简单的接口. 只要有办法通过Javascript连接到闪电钱包,就可以在Bitcoin Connect中为它创建连接器. 我们欢迎为新的连接器提供的一切捐助!

这是否适用于移动浏览器和移动PWA,还是没有WebLN扩展的桌面浏览器?

没错! 这是主要的好处.

它是否与桌面扩展功能相通 ?

对 它会使用桌面扩展作为默认连接符, 如果它存在的话.

我可以把它连接到我的手机钱包吗?

这取决于。 连接到您的闪电节点 / 钱包需要同步, 这样您就可以在移动网站或PWAs上使用 Bitcoin Connect .

一个用户能连接任何闪电钱包吗 ?

它只对模式中显示的连接器有效. 其中一些连接器(如Alby浏览器扩展)允许自己连接多个钱包. 随意贡献来添加一个新的连接器.

如果用户离开页面或关闭浏览器,它是否"记得"?

对 您的连接已保存到本地Storage

安全吗?

在您决定连接钱包的网站中, 您应该有一定的信任度, 并且确保不会出现恶意的第三方脚本来读取钱包连接配置, 无论是从内存还是存储中。 我们强烈建议添加 CSP规则 进入您的网站并跟随 最佳做法 来预防XSS.

推荐具有预算控制或确认对话框的连接器( Alby extension 或 NWC), 这样您就可以完全控制您的连接 .

为了把这个添加到网站,我需要做什么?

  1. 添加“ 连接钱包” 按钮
  2. 等待连接事件( 使用窗口. add EventListener) , 然后请求用窗口支付发票 。 网络ln

支持什么连接器 ?

如果用户用另一个钱包支付, 为什么模式会保持开放 ?

比特币连接无法检测外部支付. 由你的应用软件来检测付款,然后通过程序关闭模式 closeModal 函数.

为什么是窗户。 连接后未设置 ?

全球 window.webln 如果有多个提供者,对象可以被推翻,从而导致出乎意料的行为。 我们建议使用 requestProvider 函数以获取 WebLN 提供者,而不是依赖全局窗口对象.

为什么Bitcoin Connect在一些页面上不起作用?

Bitcoin Connection 必须在根元件上或每个需要webln的元件上导入,以确保webln可用. 如果您仅在设置页面中导入按钮, 您仍需要导入您想要进行闪电付款的库 。 我们建议使用 requestProvider 函数.

已知问题

  • NWC连接器在不安全的情况下不工作于iOS,因为窗口. 密码. subtle 不可用 。 如果在您的电话中测试, 请运行 https 服务器或使用 https 隧道 .

🔥 立特

这个项目由Lit提供动力.

见 开始吧 在Lit网站获取更多信息.

许可证

麻省理工学院

版本与发布记录

@getalby/bitcoin-connect 共发布 79 个版本,首次发布于 2023/08/28;过去 12 个月发布了 5 个版本。

版本发布日期距今
3.12.3latest2026/05/235 个月前
3.12.22026/02/188 个月前
3.12.12026/02/069 个月前
3.12.02026/02/059 个月前
3.11.52025/12/0811 个月前
3.11.42025/10/221.1 年前

其他发布通道:alpha → 1.1.1,beta → 3.7.0-beta.1。

关于 @getalby/bitcoin-connect 的常见问题

@getalby/bitcoin-connect 是什么?

用WebLN连接到闪电钱包和为网站提供动力的Web组件

如何安装 @getalby/bitcoin-connect?

在项目目录运行 npm install @getalby/bitcoin-connect,或使用 pnpm add / yarn add / bun add。

@getalby/bitcoin-connect 支持 TypeScript 吗?

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

@getalby/bitcoin-connect 支持 ESM 还是 CommonJS?

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

@getalby/bitcoin-connect 可以商用吗?

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

@getalby/bitcoin-connect 的下载量有多少?

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

@getalby/bitcoin-connect 还在维护吗?

最新版本 3.12.3 发布于 2026/05/23(5 个月前);至今共发布 79 个版本,其中过去 12 个月发布了 5 个;首次发布于 2023/08/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。