安装

根据你的环境安装 CCC——React 前端、Node.js 后端或自定义 UI。

不知道从哪里开始？快速上手指南提供了从零搭建 React 项目的完整流程。需要了解特定包或 TypeScript 配置细节时，再回到本页查阅。

CCC 拆分为多个职责明确的包，按你的环境选择对应的包：

包名	适用场景
`@ckb-ccc/connector-react`	React 应用
`@ckb-ccc/shell`	Node.js 脚本和后端
`@ckb-ccc/connector`	Web Component（框架无关）
`@ckb-ccc/ccc`	自定义 UI、手工管理 Signer

npm install @ckb-ccc/connector-react

yarn add @ckb-ccc/connector-react

pnpm add @ckb-ccc/connector-react

在应用根节点包裹 ccc.Provider，挂载钱包连接器 UI，并让 CCC context 在整个应用中可用：

使用 Next.js App Router 或其他 RSC 方案？在任何导入 ccc.Provider 或 ccc.useCcc 的文件顶部加上 "use client"。

app.tsx

"use client";

import { ccc } from "@ckb-ccc/connector-react";

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <ccc.Provider name="My CKB App" icon="/icon.png">
      {children}
    </ccc.Provider>
  );
}

在任意子组件中调用 ccc.useCcc()，即可打开连接器并获取当前活跃的 Signer：

component.tsx

"use client";

import { ccc } from "@ckb-ccc/connector-react";

export function ConnectButton() {
  const { open, wallet, signerInfo } = ccc.useCcc();

  return signerInfo ? (
    <p>已连接：{wallet?.name}</p>
  ) : (
    <button onClick={open}>连接钱包</button>
  );
}

npm install @ckb-ccc/shell

yarn add @ckb-ccc/shell

pnpm add @ckb-ccc/shell

@ckb-ccc/shell 包含 @ckb-ccc/core 的全部能力——地址、字节处理、Client、交易、Signer，并额外集成了 Spore 数字对象、SSRI 合约和用户自定义代币（UDT）等领域专用模块。它是脚本、后端和 CLI 工具的最佳选择。

script.ts

import { ccc } from "@ckb-ccc/shell";

const client = new ccc.ClientPublicTestnet();
const signer = new ccc.SignerCkbPrivateKey(client, process.env.PRIVATE_KEY!);

const address = await signer.getRecommendedAddress();
console.log("Address:", address);

npm install @ckb-ccc/connector

yarn add @ckb-ccc/connector

pnpm add @ckb-ccc/connector

导入该包后，<ccc-connector> 自定义元素会自动注册，无需额外配置：

main.ts

import { ccc } from "@ckb-ccc/connector";

index.html

<ccc-connector></ccc-connector>

npm install @ckb-ccc/ccc

yarn add @ckb-ccc/ccc

pnpm add @ckb-ccc/ccc

需要完全掌控钱包连接 UI 时，使用 @ckb-ccc/ccc。它集成了所有钱包——EIP-6963（EVM）、JoyID、NIP-07（Nostr）、OKX、UniSat、UTXO Global、Xverse 等——但不提供任何预置 UI：

custom-ui.ts

import { ccc } from "@ckb-ccc/ccc";

const client = new ccc.ClientPublicTestnet();
const controller = new ccc.SignersController();
let wallets: ccc.WalletWithSigners[] | undefined;

// 获取所有可用 Signer
await controller.refresh(client, (w) => (wallets = w));
if (!wallets) {
  throw new Error("Unexpected not wallets");
}
wallets.forEach((wallet) => {
  console.log(
    wallet.name,
    wallet.signers.map(({ name }) => name),
  );
});

const signer = wallets[0].signers[0].signer;

// 连接 Signer
await signer.connect();
console.log("Connected");

// 签名消息测试
const signature = await signer.signMessage("Hello world");
console.log(signature);

详细操作步骤参见连接钱包指南。

导入方式

所有 CCC 包均暴露相同的 ccc 命名空间，无论使用哪个包，导入写法完全一致：

import { ccc } from "@ckb-ccc/<package-name>";

const tx = ccc.Transaction.from({ ... });
const amount = ccc.fixedPointFrom("100");

底层内部 API 通过 /advanced 入口导出 cccA：

import { cccA } from "@ckb-ccc/<package-name>/advanced";

cccA 中的 API 不保证稳定性，可能随时变更而不另行通知。仅在 ccc 无法满足需求时使用。

TypeScript 配置

CCC 使用 Package Entry Points 实现 tree-shaking。在 tsconfig.json 中将 moduleResolution 设为 node16、nodenext 或 bundler，且不要禁用 resolvePackageJsonExports：

tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

如果遇到报错 Property '*' does not exist on type 'typeof import(".../@ckb-ccc/...")'，通常是 moduleResolution 配置有误。详情参见 TypeScript 模块解析文档。

安装

导入方式

TypeScript 配置

目录