原文作者：PaperMoon团队

Polkadot SDK 提供的 Parachain Template 已经内置了一套基础可用的 Runtime，其中包含多个默认的 FRAME 模块（Pallet），帮助开发者快速启动平行链开发。

但在实际项目中，我们往往需要引入更多功能模块，例如批量交易、多签支持、资产管理等。这就需要我们手动将新的 Pallet 集成到 Runtime 中。

本文将以 pallet-utility 为示例，完整讲解如何：
    •    添加已有 Pallet 依赖
    •    配置 Pallet 的运行参数
    •    注册到 Runtime
    •    编译并本地测试
    •    使用 Polkadot.js 与新 Pallet 交互

Utility Pallet 简介

pallet-utility 提供了重要的辅助功能，包括：
    •    批量交易（Batch）
    •    组合调用（BatchAll）
    •    Origin 派生调用（asDerivative）

常用于：
    •    一次提交多个交易
    •    原子化操作
    •    复杂交易组合

在很多生产级链中都属于基础组件。

准备工作

在开始之前，请确保你已经具备：
    •    已安装 Polkadot SDK 相关依赖
    •    可正常编译运行的 Parachain Template
    •    Rust 开发环境配置完成

添加 Pallet 依赖

1. 修改 runtime/Cargo.toml

Polkadot SDK 采用 Monorepo 结构，大部分官方 Pallet 都通过 polkadot-sdk features 启用。

打开：

runtime/Cargo.toml

在 [dependencies] 中找到 polkadot-sdk，添加 pallet-utility：

polkadot-sdk = { workspace = true, features = [
    "pallet-utility",
    "cumulus-pallet-aura-ext",
    "cumulus-pallet-session-benchmarking",
    # 其他 features
], default-features = false }

2. 添加自定义 Pallet（可选）

如果是自己开发的 Pallet：

custom-pallet = { path = "../pallets/custom-pallet", default-features = false }

同时确保已加入 workspace。

启用 Standard Library 特性

Runtime 会编译为：
    •    Native（二进制，用于测试）
    •    Wasm（链上运行）

Native 环境需要 std 支持。

检查 features 配置

在 runtime/Cargo.toml 中：

[features]
default = ["std"]

std = [
    "codec/std",
    "cumulus-pallet-parachain-system/std",
    "log/std",
    "polkadot-sdk/std",
    "scale-info/std",
]

确保包含：

"polkadot-sdk/std"

自定义 Pallet 情况

需要手动添加：

"custom-pallet/std"

理解 Pallet 的 Config Trait

每个 Pallet 都通过 Config Trait 定义运行时依赖。

Utility Pallet 的 Config 如下：

pub trait Config: frame_system::Config {
    type RuntimeEvent;
    type RuntimeCall;
    type PalletsOrigin;
    type WeightInfo;
}

含义说明：

类型	作用
RuntimeEvent	事件系统接入
RuntimeCall	允许调用其他 Pallet
PalletsOrigin	Origin 操作支持
WeightInfo	权重计算

在集成前，建议先阅读对应 Pallet 的 Config 定义。

实现 Config Trait

打开：

runtime/src/configs/mod.rs

在文件末尾添加：

/// Configure the utility pallet
impl pallet_utility::Config for Runtime {
    type RuntimeEvent = RuntimeEvent;
    type RuntimeCall = RuntimeCall;
    type PalletsOrigin = OriginCaller;
    type WeightInfo = pallet_utility::weights::SubstrateWeight<Runtime>;
}

说明：
    •    RuntimeEvent：统一事件类型
    •    RuntimeCall：全局调用枚举
    •    OriginCaller：Runtime 内部 Origin 枚举
    •    WeightInfo：默认权重实现

注册到 Runtime Construct

下一步需要将 Pallet 注册到 Runtime。

打开：

runtime/src/lib.rs

找到：

#[frame_support::runtime]
mod runtime {

在其中添加：

#[runtime::pallet_index(50)]
pub type Utility = pallet_utility;

示例：

#[runtime::pallet_index(0)]
pub type System = frame_system;

#[runtime::pallet_index(1)]
pub type ParachainSystem = cumulus_pallet_parachain_system;

// ...

#[runtime::pallet_index(50)]
pub type Utility = pallet_utility;

注意事项
    •    pallet_index 必须唯一
    •    不可重复
    •    通常建议预留区间

错误示例：

Duplicate pallet index

会导致编译失败。

编译验证 Runtime

回到项目根目录：

cargo build --release

确保：
    •    无编译错误
    •    无 Trait 未实现错误
    •    无 feature 缺失

此步骤可验证整体集成是否正确。

运行本地链测试

1. 生成 Chain Spec

使用 chain-spec-builder：

chain-spec-builder create -t development \
--relay-chain paseo \
--para-id 1000 \
--runtime ./target/release/wbuild/parachain-template-runtime/parachain_template_runtime.compact.compressed.wasm \
named-preset development

生成：

chain_spec.json

2. 启动节点

polkadot-omni-node --chain ./chain_spec.json --dev

确认：
    •    节点启动成功
    •    开始出块
    •    无 Runtime 报错

使用 Polkadot.js 验证 Pallet

1. 连接节点

访问：

https://polkadot.js.org/apps

连接本地节点：

ws://127.0.0.1:9944

2. 提交 Extrinsic

路径：

Developer → Extrinsics

选择：
    •    Pallet：utility
    •    可见方法：

方法	功能
batch	批量执行
batchAll	原子批量
asDerivative	派生账户调用

如果可以正常显示，说明集成成功。

总结

通过本文流程，你已经完成：

✅ 添加 Pallet 依赖
✅ 启用 std 特性
✅ 实现 Config Trait
✅ 注册 Runtime
✅ 编译验证
✅ 本地运行
✅ UI 交互测试

整体流程可概括为：

依赖 → 配置 → 注册 → 编译 → 测试

实践建议

1. 开发顺序建议

推荐流程：
    1.    先看 Config
    2.    再配 Cargo
    3.    后写 impl
    4.    最后注册

避免反复调试。

2. 常见报错来源

错误	原因
missing std	未启用 std
trait not implemented	Config 缺类型
duplicate index	index 冲突
unresolved import	feature 未启用

3. 进阶方向

掌握本流程后，可以继续学习：
    •    多 Pallet 组合设计
    •    自定义 Weight
    •    Benchmark 集成
    •    Runtime 升级
    •    XCM 交互

这些都是生产级链开发的关键能力。

原文链接：https://docs.polkadot.com/parachains/customize-runtime/add-existing-pallets/