铺垫了那么多现在直接进入实操。这篇东西是我自己从零开始用Substrate开发一条链的过程记录里面包含了我对框架的理解、核心模块的拆解、踩过的坑以及我觉得新手最应该提前知道的那几件事。内容不会太“教科书”更多是站在一个实际动手做过项目的人的角度告诉你哪些地方值得花时间、哪些地方可以暂时跳过。如果你正准备入坑希望这篇能帮你省下几个月的摸索时间。1. 内容整体设计与思路拆解1.1 为什么选Substrate它到底解决什么问题先回答一个很多人纠结的问题做一条链为什么不用Fabric、不用Cosmos SDK、不用EOSIO偏偏用Substrate我的看法是Substrate的定位和它们不一样。Fabric更多是联盟链的“企业级框架”它的重心在权限管理、通道隔离和可审计性适合业务方明确、节点数目有限的场景。Cosmos SDK擅长做跨链资产和生态互通它的模块化思路很棒但不同链之间的资产标准和治理模型相对统一灵活性反而受限。而Substrate的核心哲学是“状态转换函数可自由定义网络与共识可插拔”——它给开发者的自由度是这几个框架里最高的。说得更直白一点如果你未来想做一条具备独特业务逻辑的链比如自定义的治理模型、特殊的资产发行规则、甚至一个完全新奇的共识机制Substrate基本是唯一能让你不用从零写P2P网络和数据库的框架。它把链的“骨架”搭好了你只需要填充“血肉”。从另一个角度看Substrate也是学习区块链底层原理很好的教材。因为它的代码结构本身就体现了区块链的核心分层共识、网络、存储、执行、治理。你哪怕不写任何业务光是读它的源码就能把“一条链是怎么跑起来的”这件事搞清楚。1.2 核心架构拆解节点、运行时、存储三层模型Substrate的架构可以浓缩成三个关键词节点Node、运行时Runtime、存储Storage。节点负责区块链网络中的一切“外部”事务比如P2P节点间的连接管理交易池的接收、排序、广播区块的同步和验证RPC接口对外提供服务链下工作机Off-chain Worker运行环境Runtime则是一条链的“业务大脑”。它定义了状态转换函数也就是当一笔交易被确认执行后链上状态如何变化。Substrate最革命性的一点是Runtime被编译成WebAssemblyWasm字节码区块中的每笔交易都要在这个Wasm环境中解释执行。好处是一条链的Runtime可以通过链上治理升级不需要硬分叉。坏处是Wasm解释执行比原生代码慢所以Substrate又做了一个“执行优先级”的设计——优先用本地原生代码执行验证时用Wasm确保一致性。存储这块Substrate使用了自己的一套键值数据库抽象底层可以接RocksDB或者ParityDB。它把所有的链上状态账户余额、资产、存证、投票记录都映射成一个个简单的键值对读取和写入都被封装成高效的操作接口。对于开发者来说最需要关心的是Runtime因为你写的所有业务逻辑最终都会变成Runtime中的Pallet。理解这三层模型之后再去看Substrate的项目结构就不会再迷路了。2. 核心细节解析与实操要点2.1 项目结构Node与Runtime的分离一个典型的Substrate项目通常包含两个大目录node和runtime。如果你用官方的substrate-node-template作为起点这个结构大概长这样node/包含节点二进制相关的代码。比如节点命令行参数你要监听哪个端口、数据库存在哪、RPC如何配置、链规格Chain Spec的定义、Executor和共识相关的服务配置。runtime/包含一段独立的、编译成Wasm的运行时。里面有系统模块System Pallet、余额模块Balances Pallet、交易手续费模块Transaction Payment Pallet、模板Pallet等等。pallets/这里存放你自定义的Pallet每一个Pallet都是独立的Rust Crate。模板自带一个template-pallet方便你参考和修改。这个分离设计非常有价值。因为runtime编译成Wasm之后可以被打包进区块历史中支持链上动态升级。而node只是执行环境节点版本可以落后于Runtime版本也不会影响共识。2.2 环境搭建的完整实操从Rust工具链到初始化模板这一步看起来简单但不少新手会卡在最后一步——WebAssembly编译目标没装。我直接给出完整步骤。首先安装Rust工具链。Substrate要求至少稳定版Rust但部分底层依赖可能需要nightly。建议用rustup管理curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup default stable rustup update rustup target add wasm32-unknown-unknown --toolchain stable如果你平时用nightly也记得给nightly加上这个targetrustup target add wasm32-unknown-unknown --toolchain nightly然后安装系统依赖。在Ubuntu/Debian上大概需要这些包apt update apt install -y build-essential clang git libssl-dev pkg-configclang是必须的Substrate编译Wasm时需要它作为底层工具链。macOS用户则需要装Xcode Command Line Tools和Homebrew。接下来获取官方模板git clone https://github.com/substrate-developer-hub/substrate-node-template cd substrate-node-template首次编译会比较久通常在10到30分钟之间取决于机器性能。这时候别急去泡杯咖啡。等到编译成功你就可以先跑起来试试了。2.3 Pallet开发写一个存证或转账业务的完整思路Pallet是Substrate业务逻辑的基本单元。用官方术语说它是一组“可组合的Runtime模块”。我建议第一个练习项目不要做太复杂的东西选“存证”或“简单转账”这类单业务逻辑最好。一个经典存证Pallet的结构包含下面这些元素Config Trait定义Pallet需要从Runtime继承的类型比如Event类型、AccountId类型。Storage链上状态的存储声明。比如一个Documents映射键是账户ID值是存证数据的哈希。Events链上状态发生改变后要记录的事件。比如“文档已存证”。Errors可能失败的操作比如“文档已存在”“数据过长”。Extrinsics可调用函数实际被外部调用和链上执行的一组函数。这是业务逻辑的入口。下面我用代码片段展示一个最简化的存证逻辑#![cfg_attr(not(feature std), no_std)] use frame_support::{decl_module, decl_storage, decl_event, ensure}; use frame_system::ensure_signed; pub trait Config: frame_system::Config { type Event: FromEventSelf IsTypeSelf as frame_system::Config::Event; } decl_storage! { trait Store for ModuleT: Config as TemplateModule { Documents get(fn documents): map hasher(blake2_128_concat) T::AccountId Vecu8; } } decl_event! { pub enum EventT where AccountId T as frame_system::Config::AccountId { DocumentStored(AccountId, Vecu8), } } decl_module! { pub struct ModuleT: Config for enum Call where origin: T::Origin { fn deposit_event() default; #[weight 10_000] pub fn store_document(origin, document: Vecu8) - dispatch::DispatchResult { let who ensure_signed(origin)?; ensure!(document.len() 100, Document too large); DocumentsT::insert(who, document.clone()); Self::deposit_event(RawEvent::DocumentStored(who, document)); Ok(()) } } }这段代码虽然老式新版本的FRAME已经在逐步替换为#[pallet::...]写法但逻辑原理完全一样。你可以在这个基础上扩展出“存证校验”“按时间戳存证”“权限控制存证”等更丰富的功能。2.4 手写实现时的注意事项安全性、费率和权限抛开代码语法我想专门强调几点新手容易忽略的事情第一注意权限检查。链上的调用者是一个Origin可能是签名账户、也可能是根账户、甚至可能是一个不签名的调用。你的业务函数必须明确自己接受哪种Origin。比如存证业务用ensure_signed(origin)意思是只允许签名账户调用。如果忘了权限检查任何节点都能调用。这在真实项目中会是一个极其严重的安全漏洞。第二注意Weight校准。你标注的#[weight 10_000]会被用于计算交易费用和限制每个区块的可执行交易数。如果实际执行比标注重很多会导致区块执行超时或者被区块生产者拒收。严谨的项目里Weight要用基准测试Benchmark工具测出来而不是拍脑袋写一个数字。第三注意存储设计。Substrate的存储读取是影响性能的关键因素。如果你的Pallet会频繁读存储尽量用get而不是迭代整个映射如果你需要遍历尽量用双键映射或存储“迭代器”。在实际生产中存储设计不合理区块时间会被严重拖慢。第四不要忽略事件参数的类型限制。事件里如果放了自定义结构体或者复杂类型会导致链下索引工具难以解析。事件参数尽量用基础类型或经过Encode/Decode验证的类型。2.5 工具选型与开发周期哪些工具值得装除了Rust和substrate-node-template有几个工具能显著提升开发体验Subkey用来生成和管理密钥对、签名交易、计算地址。它是Substrate钱包相关操作的基础工具。用cargo install subkey --locked安装。Polkadot.js Apps连接Substrate链的全功能前端工具在浏览器中即可操作。你可以查看账户、发送交易、查询存储、调用Runtime接口。开发时几乎是“标配”。Frontier模板如果你想把Substrate做成一个EVM兼容链可以用这个模板。它集成以太坊的RPC、交易格式和地址格式让Solidity合约可以直接跑在Substrate链上。Squid / Subsquid用于链上数据索引和GraphQL API生成。当你的业务数据需要展示给前端时这个工具链非常有用。我个人建议的开发节奏是先跑通一条单节点开发链再写一个简单Pallet最后把前端接上。一次性铺开太多工具只会增加调试复杂度。3. 实操过程与核心环节实现3.1 用开发模式启动一条单节点链环境准备好之后直接启动本地开发链cargo run -- --dev注意--dev模式会自动创建一个临时链不需要指定数据库路径也不会污染你的正式数据。启动之后能看到区块在不断产生2025-xx-xx 08:00:00 Substrate Node 2025-xx-xx 08:00:00 ✌️ version x.x.x 2025-xx-xx 08:00:00 ❤️ by Substrate DevHub, 2019-2024 2025-xx-xx 08:00:00 Chain specification: Development 2025-xx-xx 08:00:00 Node name: ... 2025-xx-xx 08:00:00 Role: AUTHORITY 2025-xx-xx 08:00:00 Database: RocksDb at /tmp/... 2025-xx-xx 08:00:00 ⛓ Native runtime: template-1 (template-1.tx1.au1) 2025-xx-xx 08:00:01 Idle (0 peers), best: #0 (0x...), finalized #0 (0x...) 2025-xx-xx 08:00:06 Idle (0 peers), best: #1 (0x...), finalized #0 (0x...)如果看到best和finalized不断增长说明网络已经在正常出块。之后你就能通过RPC接口做各种交互了。3.2 通过Polkadot.js Apps连接并完成首次交易链跑起来后打开Polkadot.js Apps点击左上角的网络切换选择“Development”并填入本地节点地址WS RPC地址通常是ws://127.0.0.1:9944HTTP RPC地址通常是http://127.0.0.1:9933连接上之后可以在“Accounts”页面看到默认的Alice、Bob等开发账户。Alice默认有大量余额可以直接用来测试。接下来我们完成第一笔交易。在Polkadot.js Apps里进入“Developer” - “Extrinsics”。选择templateModule-storeDocument。在document字段输入你想存证的内容比如hello substrate。点击“Submit Transaction”用Alice账户签名并提交。交易成功后你会在区块浏览器中看到事件templateModule.DocumentStored被触发。此时再到“Developer” - “Chain state”页面选择templateModule-documents就能查到刚才存进去的数据。这个流程可以让你直观地感受到链上状态如何变化、交易如何产生、事件如何被记录。3.3 写Pallet单元测试测试驱动的链上逻辑验证链上逻辑不能光靠前端手动验证。Substrate框架内置了完善的单元测试支持可以在不启动节点的情况下模拟Runtime环境并执行Pallet的调用。模板里的pallet/src/tests.rs会自带两个示例测试。你可以在此基础上扩展。用我们刚才的存证模块举例#[cfg(test)] mod tests { use super::*; use frame_support::{assert_ok, assert_err}; use sp_runtime::BuildStorage; #[test] fn store_document_works() { new_test_ext().execute_with(|| { assert_ok!(TemplateModule::store_document(Origin::signed(1), vec![1, 2, 3])); assert_eq!(TemplateModule::documents(1), vec![1, 2, 3]); }); } #[test] fn store_document_rejects_oversize() { new_test_ext().execute_with(|| { let big_doc vec![0u8; 101]; assert_err!( TemplateModule::store_document(Origin::signed(1), big_doc), Document too large ); }); } }注意new_test_ext().execute_with(|| { ... })这个模式。它创建了一个内存中的Runtime执行环境把存储初始化为测试所需的状态然后跑闭包里的逻辑。每一段测试代码都互相隔离所以你可以大胆地构造各种边界情况。在pallet目录下运行cargo test如果所有测试通过春节快乐。在实际项目里我会把测试覆盖率作为一个重要的发布指标。尤其是涉及转账、资产、权限控制的Pallet测试能提前拦截大量低级错误。3.4 从单节点到多节点搭一个本地双节点网络单节点开发模式方便但你迟早要在一起跑多个节点测试网络行为。Substrate做这件事也很快关键在Chain Spec。首先生成两把密钥subkey generate --scheme Sr25519 subkey generate --scheme Sr25519把两个公钥填入node/src/chain_spec.rs中的authorities数组。同时如果你想指定初始账户余额也在chain_spec.rs里配置。随后启动两个节点# 第一个节点 ./target/release/substrate \ --chainlocal \ --validator \ --base-path/tmp/validator1 \ --node-key0000000000000000000000000000000000000000000000000000000000000001 \ --port30333 \ --rpc-port9933 \ --ws-port9944 # 第二个节点 ./target/release/substrate \ --chainlocal \ --validator \ --base-path/tmp/validator2 \ --node-key0000000000000000000000000000000000000000000000000000000000000002 \ --port30334 \ --rpc-port9934 \ --ws-port9945 \ --bootnodes/ip4/127.0.0.1/tcp/30333/p2p/第一个节点的PeerID注意--bootnodes指定另一个节点的P2P地址。PeerID会自动从日志里输出格式类似12D3KooW...。两个节点启动后如果你看到“Imported N blocks”在持续增长就说明它们已经完成共识同步了。多节点模式下要留意几个问题一是每个节点的--base-path要不同否则数据库会冲突二是--chain local对应的Chain Spec要完全一致否则无法握手三是端口不能冲突。3.5 处理Runtime升级用这条链做一次真正的链上变更Runtime升级是Substrate的招牌功能。要做到这一点需要把编译好的Runtime Wasm提交到链上并通过治理机制完成更新。简化的流程是这样的编译好最新的Runtimecargo build --release拿到编译生成的Wasm文件位置一般在target/release/wbuild/下。在Polkadot.js Apps中找到“Developer” - “Extrinsics”选择sudo模块的sudoUncheckedWeight调用setCode把Wasm字节码上传。等待下一个区块或者在测试模式下等待1个区块链就会执行新的Runtime代码。我实际体验下来这个过程很有仪式感但也很吓人。因为你可能一秒钟前还在用旧逻辑一秒钟后链上规则全变了。为了安全一定要在测试网充分测试之后再做正式链升级。4. 常见问题与排查技巧实录4.1 编译启动类的典型问题与解决问题1编译时报错说找不到wasm32-unknown-unknown这基本是环境问题。用下面的命令确认rustup target list --installed如果没装补上rustup target add wasm32-unknown-unknown问题2节点启动时报“Unable to load database”通常是因为--dev模式和自定义路径冲突或者没有给--base-path指定可写目录。开发模式下直接删掉临时数据目录或者用--tmp参数让节点自动清理。问题3节点启动后经典出块但Polkadot.js连不上先确认RPC端口监听curl http://127.0.0.1:9933 -H Content-Type: application/json -d {jsonrpc:2.0,method:system_health,params:[],id:1}如果返回结果正常再去检查Polkadot.js里填的WS地址注意ws和wss的区别。浏览器默认会拦截混合内容最好用ws://127.0.0.1而不是局域网IP。4.2 Runtime逻辑类的问题与解决问题1交易提交成功但状态没有变化这种问题大概率是事件没有触发、或者存储写入的键不符合预期。建议先查看事件日志确认deposit_event是否执行再到“Chain state”面板检查相关存储项。问题2Pallet调用时报“Module/TemplateModule: Document already exists”这是存储冲突。原因是同一个账户已经有了同名数据。解决办法是在业务逻辑里先做查询判断或者用(AccountId, DocumentId)双键映射来区分多条数据。问题3升级Runtime后前端无法签名元数据变化会导致Polkadot.js无法识别新接口。刷新浏览器页面重新读取链的元数据即可。如果还不行清除浏览器缓存。4.3 我把这些整理成了一张速查表下面这张表来自我自己的实战笔记方便快速对照现象可能原因快速检查/解决方式编译失败rustup target缺失缺少wasm targetrustup target add wasm32-unknown-unknown节点启动后不出块缺少验证人配置确认是否以--validator启动Chain Spec中authorities是否有值交易发出去前端显示失败外部调用了无权限函数检查Pallet的Origin权限必要时用ensure_signed事件没触发事件类型定义或deposit_event未调用检查事件类型是否纳入Runtime的construct_runtime!宏多节点无法同步Chain Spec不一致或bootnode错误确保所有节点使用相同Chain Spec正确指定--bootnodes存储读取速度很慢存储结构设计不合理尽量用哈希键而不是线性遍历避免重复递归读取链上升级后接口变化元数据过期刷新Polkadot.js必要时重启前端会话这张表不是一个万能答案但它能帮你把“最常见的那80%”的坑提前排掉。剩下的问题就靠你自己多读代码、多跑日志去定位了。4.4 一个我自己曾经卡了很久的小细节最后分享一个我当年卡了很久的细节。在Substrate中直接调用存储方法时会用get关键字比如StorageMap::get(key)但有些老版本的API是get(key)和contains_key(key)两个不同方法。有一次我误把查询逻辑写成了Documents::contains_key(who)但实际想判断的是“是否存在某账户”结果逻辑翻转测试怎么跑都不过。这种API层面的坑通常在更新Substrate版本后会突然出现。建议你升级版本后不要直接拉代码编译而是先看官方发版日志和迁移指南。如果你用的是旧模板最好尽快迁移到新版。5. 最后说点开发体验和心得我不想用那种“一定是这样”的总结语气因为Substrate迭代真的快今天写的东西过几个月可能就被新方式替代了。但有些核心体验我觉得是长期有效的。第一个体验是Substrate的学习曲线非常陡但突破前期的“陡”之后后面反而会越来越顺。最难的其实是理解框架的抽象层级为什么Runtime是Wasm为什么事件要单独定义为什么存储要手动声明类型。一旦理解这些设计背后的原因写业务逻辑就不再是照葫芦画瓢而是有根有据的设计。第二个体验是模板代码永远是最好的起点。无论你有多熟练从官方现成的模板扩展都比从零搭框架快得多。模板里已经处理了大量边界情况比如链规格、创世配置、RPC接口这些内容你一开始不需要自己重写。等真正理解之后再尝试替换默认模块也不迟。第三个体验是这个框架适合用来做“别人没做过的东西”。如果只是发一个标准ERC20代币或者是做一条普通PoS链用Substrate有点大材小用。但如果你想让链的业务逻辑跟传统互联网业务深度绑定比如让链上的存证能够自动触发线下协议、让数据隐私与链上公开性做动态平衡这时Substrate的灵活度才能真正显现出来。最后分享一个实操小技巧开发时尽量把调试日志打开。在启动节点时加-l runtimedebug你就能在终端看到很多Runtime内部信息。这在排查“为什么这笔交易没有按预期走”的时候帮助特别大。千万别只依赖前端界面的反馈那往往不够细。
