「Substrate」这个词你单独丢进搜索引擎，前几页大概率会出来一堆不相干的东西：生物学里的培养基、化学里的底物、材料学里的基板。但在区块链开发者圈子里，它指的是那个用 Rust 写的区块链开发框架。我第一次想自己造一条链的时候，天真地以为核心工作就是写业务逻辑，结果光是把 P2P 网络、交易池、区块头校验、共识这几个轮子自己造一遍，就足够消耗掉大半年的业余时间。后来我换到 Substrate，才发现框架已经把节点的脏活累活全包了，你要做的其实是专注于链上的状态转换逻辑。
这篇东西我会围绕 Substrate 从「为什么用它」讲到「怎么用」，再讲到我实际开发中踩过的几个坑。适合两类人：一类是想自己发一条链但还没选好技术方案的人，可以先看第一二章判断方向；另一类是已经决定用 Substrate、准备从模板开始动手的人，可以直接跳到第四五章照着操作。我会尽量说人话，不会堆官方文档里那种绕来绕去的定义。
1. 从零写一条链太痛了：Substrate 解决的核心问题
1.1 区块链开发的经典困局：共识、存储、网络都要自己造
我在真正接触 Substrate 之前，自己用 Go 写过一条极简的链。当时我天真地列了一下需求：一个区块结构、一笔转账、一个哈希链表，听起来不多。但真正动手才发现，任何一个能勉强称得上区块链的系统，都必须同时解决几个基础问题：节点之间怎么发现彼此并同步数据，交易池怎么管理待确认交易，收到的区块怎么验证签名和状态根，多个节点之间怎么达成一致，状态数据存在哪、怎么高效读写。
这些事每一个单拎出来都是独立的分布式系统课题，而且它们之间还互相耦合。我在写 P2P 同步模块的时候，发现自己要处理的不只是 TCP 连接，还要考虑消息去重、分叉选择、孤儿区块、区块广播风暴。写到一半我就明白了一个道理：区块链的难点从来不在业务逻辑，而在它脚下那一大坨基础设施。大部分想做链的人，真正想做的只是某一条业务规则，比如积分体系、供应链溯源、游戏资产流转，而不是重新发明一遍共识。
1.2 Substrate 的分层答案：基础设施全给，业务逻辑留给你
Substrate 的解法非常直白：它把所有区块链通用的东西直接做成可复用组件，你需要关心的只有 Runtime 层。所谓 Runtime，就是这条链上状态转换函数的集合——给一笔交易进来，我该不该接收，接收之后账本变成什么。
具体来说，Substrate 帮你做好的东西包括：
- 网络层：基于 libp2p 的节点发现、连接管理、区块同步协议，开箱即用。
- 共识层：提供 Aura、Babe、Grandpa、Manual Seal 等多种共识引擎，可以按场景切换。
- 存储层：基于 Merkle Patricia Trie 的状态存储，区块头的状态根自动计算，不需要你操心默克尔证明。
- 交易池和区块执行引擎：交易进出池子、打包区块、执行 Runtime、出块，整条流水线都给你搭好了。
- 链上升级机制：Runtime 以 WebAssembly 形式存在链上，可以通过
set_code这类调用原地升级，不需要硬分叉。
我第一次跑通substrate-node-template的时候，cargo run -- --dev一启动，日志里就刷刷地出块。我当时有点恍惚：这条链已经有 P2P 端口、有 RPC、有浏览器能连，我一行业务逻辑都还没写。这就是框架的价值——它把从零到「能出块的链」的时间压缩到了半天以内。
1.3 适用场景和边界：不是所有项目都该上 Substrate
我见过不少人一上来就问「Substrate 能不能做 NFT 市场」「能不能做积分系统」，这些问题本身没毛病，但要分清场景。Substrate 适合的是你要做一条独立链或者平行链，你对共识参数、治理机制、手续费模型、存储结构有自主控制需求的情况。比如联盟链里节点准入用 PoA，比如游戏链想要零手续费但限制每区块交易数，这些在通用合约链上很难定制，而在 Substrate 里不过是改配置的事。
如果你只是想发一个通证、做一个去中心化应用，那完全没有必要用 Substrate，直接在现成的合约链上写 Solidity 合约快得多。Substrate 的代价是学习曲线陡峭，Rust 语言本身、FRAME 宏体系、类型系统都要花时间适应。拿我自己举例，头两周几乎是边看编译报错边查文档，进度极慢。但熬过那个阶段，定制能力带来的收益是很实在的。
| 维度 | 从零自研 | Substrate 开发链 | 通用链上写合约 |
|---|---|---|---|
| 开发工作量 | 极高 | 中高 | 低 |
| 业务逻辑可定制性 | 完全自由 | 完全自由 | 受限于合约虚拟机 |
| 链级参数可定制性 | 完全自由 | 完全自由 | 几乎不可定制 |
| 升级方式 | 自己实现 | 内置 Wasm 升级 | 合约升级，链本身不可改 |
| 生态基建 | 几乎没有 | 节点、浏览器、SDK 齐全 | 基础设施最完善 |
| 学习成本 | 极高 | 高 | 中 |
2. 先绕开 Runtime 和 Client 这两个词，是理解不了框架的
2.1 节点 = Client + Runtime：发动机和发动机程序的区别
Substrate 里最核心的一对概念，我建议你用发动机来理解。Client 是整个节点的外壳，它负责网络通信、区块同步、交易池管理、RPC 服务、数据库存储，这些像发动机的机械结构，是相对固定的。Runtime 是链上状态转换规则的集合，它决定「一笔转账合法不合法」「一个区块能不能被接受」，这更像发动机里的控制程序。
这两个东西最妙的地方在于，它们通过一个明确的内在约定分离了：对同一个区块头，Client 负责验证它的密码学部分，比如签名、哈希、默克尔根，而真正执行交易之后状态是否变化正确，必须交给 Runtime 里的 Wasm 代码来判定。你完全可以只改 Runtime 而不动 Client，这就为链的升级铺了路。
区块推进的整体流程是：客户端从网络上收到或自己打包一批 extrinsic（外部事物，包括交易），把它们交给 Runtime 的execute_block函数。Runtime 按照顺序执行每一个 extrinsic，每执行一个就更新一次状态存储，最后把新的状态根写进区块头，这件事就结束了。整个过程中，Client 像一个搬运工，Runtime 像一个裁判，业务规则全在裁判那一侧。
2.2 为什么 Runtime 要编译成 Wasm：可升级的关键
Substrate 把 Runtime 编成两种形式：一种是本机执行的二进制格式，用于高效运行；另一种是 WebAssembly 字节码，存在链上。很多人不理解为什么非要搞 WAsm 这份拷贝，我实际用过之后才体会到它的价值。
当链需要升级 Runtime 逻辑时，节点通过一次普通的链上调用把新的 Wasm 代码写入存储。之后所有节点在推进下一个区块时，都从链上读取最新的 Wasm 代码并执行它，这个新区块会被整个网络以密码学方式确认。也就是说，升级不是在所有节点上统一换二进制，而是通过区块本身完成的状态更新。即使某个节点跑的还是旧版本 Client，它依然能用内置的 Wasm 解释器去执行新的 Runtime 逻辑，顶多慢一点，但不会分叉。
我最早听到「运行时升级就像 UPDATE 一条数据库记录」这个类比时还不信，后来自己跑了一次sudo system.setCode，看到一条链在不停块的情况下换了业务规则，才确认这套机制是真能用的。当然，升级逻辑易、升级数据难，这一点到第六章我再详细讲。
2.3 Extrinsic、Call、Signature：链上交易的三个层次
Substrate 里最容易被新手绕晕的概念是 extrinsic。笼统地说，凡是「从链外传入链内并触发状态变化的数据」都叫 extrinsic 或者外部事物。它分为两类：
- 签名交易：普通用户构造的转账、调用等操作，必须带签名、nonce、手续费上限。
- 未签名事务：出块节点主动注入的，比如时间戳更新这种每个区块都要有、但没有任何人能签名的操作。
而 extrinsic 内部包含的 Call，才是真正对应到某个 pallet 某个函数的调用描述。你可以把 Call 理解成一个巨大的枚举，里面列出了所有 pallet 暴露的可调用函数。前端构造一笔交易，本质就是声明「我要调balances.transfer，参数是Bob和100」，然后签名、广播，让节点把它打进区块。
我见过不少前端同学被「为什么提交易报 UnknownTransaction」卡住，其实错不在签名，而在于没搞清 nonce 和手续费限制。在 Substrate 里，nonce 和 account 索引是 frame_system 统一管理的，要么自己用 RPCsystem.accountNextIndex查，要么让 SDK 自动填充，手写的时候千万别觉得它可以省略。
2.4 State Trie 与存储：区块头的状态根是怎么来的
Substrate 的链上状态全部存放在一个基于 Merkle Patricia Trie 的键值存储里。每个存储项都有一个由 pallet 名和存储名拼接出来的确定性键，比如Balancespallet 的某个余额，键会形如0x...，值是 SCALE 编码后的数据。所有键值对放在一棵 Trie 里，树的根哈希就是状态根，被写进区块头。
这个设计的好处是：任何节点都能仅凭一个区块头验证整条链的状态是否一致，轻客户端也可以只下载它关心的那部分存储证明。坏处是我这种喜欢读原始存储的人，得习惯不靠 SQL 而是通过 RPCstate_getStorage去查。调试自定义 pallet 的时候，你会经常需要把存储键算出来或者用 polkadot.js 的 API 直接读，而不是打日志，这一点越早适应越省事。
3. 用 FRAME 往链上插拔功能：Pallet 与 Cargo 的配置
3.1 FRAME 到底是什么
FRAME 是 Substrate 提供的一套用于编写 Runtime 的模块化框架，全称是 Framework for Runtime Aggregation of Modular Entities。名字很长，用起来其实就是「一组宏加一组约定」。在 FRAME 里，一个功能模块叫 pallet，它像一个可以被插进 Runtime 的插件。
比方说，你要做一个积分系统，就写一个pallet_points，里面有积分余额的存储、加分扣分的函数、积分变动的 Event；你要做管理员角色，就用现成的pallet_sudo；你要做链上治理投票，可以接入pallet_democracy。传统开发里这叫模块化，在 Substrate 里这套模块化发生在链上逻辑层面，所以每个 pallet 最终都会影响链的状态转换规则。
pallet 之间可以互相调用，但边界很清晰。一个 pallet 通过Configtrait 声明自己在运行环境里需要什么东西，另一个 pallet 在 runtime 组装时把对应的实现注入进来。这种设计很像依赖注入：pallet_balances不关心谁在调用它，只要调用方提供了正确的AccountId和Balance类型就行。
3.2 一个最小 pallet 长什么样
我建议新手自己从头写一个极简的 pallet，而不是只改模板。下面是我写的一个计数器 pallet 的核心代码，麻雀虽小五脏俱全：
#![cfg_attr(not(feature = "std"), no_std)] pub use pallet::*; #[frame_support::pallet] pub mod pallet { use frame_support::pallet_prelude::*; use frame_system::pallet_prelude::*; #[pallet::config] pub trait Config: frame_system::Config { type RuntimeEvent: IsType<<Self as frame_system::Config>::RuntimeEvent> + From<Event<Self>>; } #[pallet::pallet] pub struct Pallet<T>(_); #[pallet::storage] pub type Counter<T: Config> = StorageValue<_, u32, ValueQuery>; #[pallet::event] #[pallet::generate_deposit(pub(super) fn deposit_event)] pub enum Event<T: Config> { ValueChanged { old: u32, new: u32 }, } #[pallet::call] impl<T: Config> Pallet<T> { #[pallet::weight(10_000)] pub fn increment(origin: OriginFor<T>) -> DispatchResult { let _who = ensure_signed(origin)?; let old = Counter::<T>::get(); let new = old.saturating_add(1); Counter::<T>::put(new); Self::deposit_event(Event::ValueChanged { old, new }); Ok(()) } } }逐个拆开说：pallet::config定义了 pallet 需要的关联类型，RuntimeEvent是每个自定义 pallet 几乎都必须声明的，它用来把 pallet 的事件转发到 Runtime 的统一事件枚举里去。pallet::storage定义了一个名为 Counter 的存储值，类型是u32，ValueQuery表示读取时如果不存在，直接返回类型的默认值0，而不是返回None。pallet::event声明了ValueChanged事件，generate_deposit宏帮我生成了deposit_event函数。pallet::call下面就是用户可以调用的交易函数。
这个 pallet 里我故意只用了最朴素的写法，注释也没写太多，因为当你第一次把它编译过的时候，宏展开后到底生成了多少代码，比任何文档都直观。如果编译报错，多半是 trait 边界缺东西，比如忘了RuntimeEvent的类型约束，或者运行时类型没实现所需的From。
3.3 在 Runtime 中组装：Cargo 依赖加 construct_runtime
写了 pallet 不等于它能跑，你必须把它注册进 Runtime。首先要在这个 pallet 的Cargo.toml里声明依赖，然后在 runtime 的Cargo.toml里依赖这个 pallet crate。以我上面的计数器为例，runtime 的Cargo.toml会有类似这样的内容：
[dependencies] pallet-counter = { path = "../pallets/counter", default-features = false, version = "4.0.0-dev" } [features] std = [ "pallet-counter/std", ]这里的关键是default-features = false，因为 Runtime 要被编译成 Wasm，而 Wasm 环境里不能用标准库，所以每个 pallet 都必须保证no_std可用。我在刚开始写的时候经常漏掉 runtimestdfeature 里那一行，结果编译出来的 Wasm 和本机二进制行为不一致，排错排到怀疑人生。
接着打开runtime/src/lib.rs，在construct_runtime!宏里注册：
construct_runtime!( pub enum Runtime { System: frame_system, Balances: pallet_balances, Counter: pallet_counter, } );然后在 impl pallet 的Configtrait 时补上关联类型：
impl pallet_counter::Config for Runtime { type RuntimeEvent = RuntimeEvent; }这一步做完，计数器 pallet 才真正成为 Runtime 的一部分，节点的 RPC 里会出现counter相关的功能，前端也能构造调用它的交易了。这里最需要养成的习惯是：每加一个 pallet，就编译一次，而不是攒一堆再编译。宏展开的错误信息往往把线索藏在几十层类型里，一次只做一处修改，你才能定位到底是谁的类型约束没对齐。
3.4 Pallet 的常见组成：除了 Call 还有 Error 和 Hooks
真正业务里你会遇到的 pallet 组成比上面这个例子多：#[pallet::error]用来声明可读的错误枚举，函数返回Err(Error::<T>::InsufficientBalance.into())时，节点会把它变成带索引的错误描述传给前端；#[pallet::hooks]用来定义区块生命周期回调，比如on_initialize在每个区块开始执行，on_finalize在区块结束执行，很多链上竞拍、结算逻辑都放在这里。
还有一个容易被忽略的 Weight 和存款机制。#[pallet::weight(...)]的值关系到交易手续费，它本质上是对计算和存储消耗的一个度量。你可以先写固定值跑通流程，但上生产之前一定要让 benchmark 生成真实的 weight。我见过一条链因为所有交易 weight 都给 10，结果一个区块能塞成千上万笔复杂交易，节点磁盘和网络会被活活拖垮。Weight 不是性能优化的细枝末节，它是链的安全边界之一。
4. 本地跑起第一条定制链：从 node-template 到前端交互
4.1 环境准备：Rust 工具链和模板克隆
Substrate 开发绕不开 Rust。我用的是官方推荐的安装方式，rustup装好之后，substrate-node-template仓库里自带了rust-toolchain.toml，这个文件会固定你编译所需的 nightly 工具链版本。
克隆和初始编译命令如下：
git clone https://github.com/substrate-developer-hub/substrate-node-template cd substrate-node-template cargo build --release这里我要提前给你打个预防针：第一次编译非常慢，视机器配置可能要 20 到 60 分钟，而且编译过程会吃掉大量内存，8GB 内存的机器建议老实开 swap。我自己的经验是，第一次不要在编辑代码的同时挂着编译，不然你的 IDE 卡到光标都挪不动。这一步的唯一目标是把模板跑通，其余都先放下。
4.2 启动开发链：--dev 参数到底做了什么
编译完成后，启动开发链：
./target/release/node-template --dev--dev不是随便加的。它会启用一个单验证人的开发网络，自动预置 Alice、Bob 等一组测试账号，并且每个账号都有花不完的余额。同时它还会去掉很多生产环境需要的鉴权和共识约束，让你可以快速测试链的功能。如果你的链需要多节点组网，就不要再加--dev，而是用--validator --alice分别启动多个节点。
启动后你会看到类似这样的日志：
2025-01-01 12:00:00 🏁 Initializing Genesis block/state 2025-01-01 12:00:01 💤 Idle (0 peers), best: #9 (0x...) 2025-01-01 12:00:06 ✨ Imported #10 (0x...)看到不断增长的#区块高度，说明链已经正常出块。默认情况下 RPC 接口开在ws://localhost:9944，P2P 端口是30333。开发链没有外部种子节点，所以日志里显示0 peers是正常的，它自己就是全网。
4.3 连接前端：Front-End Template 和 Polkadot.js
有了跑起来的节点，你需要一个直观的工具去跟它交互。官方的substrate-front-end-template是一个 React 项目，克隆下来之后：
git clone https://github.com/substrate-developer-hub/substrate-front-end-template cd substrate-front-end-template yarn install yarn start浏览器打开http://localhost:8000，它会自动连接ws://localhost:9944。界面上能看到当前区块、一组预置账号、余额转账表单、链上事件和存储查询面板。我第一次看到自己启动的链上出现实时事件流时，才真正有了「这是一条活链」的感觉。
如果不想用这套前端，也可以直接打开 Polkadot.js Apps，在设置里把 RPC 地址改成ws://127.0.0.1:9944并保存，就能通过它访问本地链。Polkadot.js 的界面虽然复杂，但它的存储查询和交易构造功能比前端模板完整得多，调试自定义 pallet 时更推荐用它。
4.4 完成第一笔转账：从 Alice 到 Bob
在开发链上做第一笔转账是建立信心的关键步骤。你可以在前端模板的账号区域看到 Alice 有大量余额，在转账表单里填收款方 Bob 和金额，点提交。
几秒钟后，区块浏览器上会出现这笔交易的事件记录，包含Balances.Transfer，带有from、to、amount三个字段。你再去查 Bob 的余额，发现已经变了。这里我想提醒一个细节：开发链上交易几乎是即时进块的，但如果你在别的网络里提交交易后迟迟不确认，先查 nonce 和手续费，再查交易池有没有被打进区块，绝大多数问题都出在这三个环节。
4.5 命令行交互：用 RPC 和 SDK 绕过前端
前端方便，但自动化测试还是得走代码。Substrate 节点暴露了一整套 JSON-RPC 接口，比如用curl直接查存储：
curl -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"state_getStorage","params":["0x...",null],"id":1}' \ http://localhost:9933这里的 storage key 是 SCALE 编码后的键，手工拼非常麻烦，所以我一般用 Python 的substrate-interface或 Rust 的substrate-api-client。写自动化冒烟测试的时候，直接构造Keyring账号往本地链发交易，比前端点半天快得多。
5. 改到自己链上的第一个真实模块：一个带事件的自定义 Pallet
5.1 先想清楚模块边界，再动手写
我在 3.2 节给的计数器 pallet，属于入门跑通用的。真到实际项目里，你要做的模块通常要复杂得多。我自己的经验是，写代码之前先用普通语言把业务规则描述清楚，再翻译成 pallet 的存储和函数。比如「用户每邀请一个新用户，双方的积分各加 100」，这就要考虑一个用户被邀请后不能重复被统计，需要存储一个邀请关系映射和一个已使用标记。
我最初犯的错就是一上来直接写存储和函数，结果做到一半发现业务规则有漏洞，存储结构必须推倒重来。把规则写下来、用假想边界场景跑一遍，再动手，成本低得多。
5.2 实现带错误处理的模块逻辑
拿一个稍微现实一点的例子：积分转账。假设我要实现一个pallet_points，用户之间可以转账积分，但不能转成负数，也不能给自己转。
核心代码如下：
#[pallet::storage] pub type Points<T: Config> = StorageMap< _, Blake2_128Concat, T::AccountId, u32, ValueQuery, >; #[pallet::error] pub enum Error<T> { InsufficientPoints, CannotTransferToSelf, } #[pallet::call] impl<T: Config> Pallet<T> { #[pallet::weight(10_000)] pub fn transfer( origin: OriginFor<T>, to: T::AccountId, amount: u32, ) -> DispatchResult { let from = ensure_signed(origin)?; ensure!(from != to, Error::<T>::CannotTransferToSelf); let from_balance = Points::<T>::get(&from); let to_balance = Points::<T>::get(&to); ensure!(from_balance >= amount, Error::<T>::InsufficientPoints); Points::<T>::insert(&from, from_balance.saturating_sub(amount)); Points::<T>::insert(&to, to_balance.saturating_add(amount)); Self::deposit_event(Event::PointsTransferred { from: from.clone(), to, amount, }); Ok(()) } }这里有两个容易踩的细节。第一，我用的是StorageMap而不是StorageValue，存储的 key 是 AccountId，value 是积分。第二，Blake2_128Concat是存储 key 的哈希方式，它决定了该 key 在 Trie 中的位置，也可以用来做遍历查询；如果你不需要按前缀遍历，用Twox64Concat更快，但安全性稍差。从官方模板的默认选择开始，不要自己乱改哈希方式，除非你很清楚攻击面。
5.3 把模块注册进 Runtime 并验证
注册流程和第三章一样：把pallet_points加进 runtime 的Cargo.toml，在construct_runtime!里注册Points: pallet_points，实现Configtrait。启动链之后，用 Polkadot.js 向points.transfer提交交易，如果收款方没有余额，会看到错误Points.InsufficientPoints。
这里我实测中最容易混淆的是事件和错误的表现形式。事件会出现在区块的 event 列表中，错误则会出现在交易的 dispatch result 里，前端如果只看 events 不看系统事件，常常以为自己调用失败「什么都没发生」。记得把system.ExtrinsicFailed这类系统事件也订阅上。
5.4 用 Rust 写单元测试：模拟 Runtime
pallet 逻辑在链上跑之前，先用单元测试验证是最省事的。Substrate 提供了frame_support里的construct_runtime!宏和sp_io::TestExternalities，可以搭一个测试用的小 Runtime：
#[cfg(test)] mod tests { use super::*; use frame_support::{construct_runtime, traits::Everything}; use sp_core::H256; use sp_runtime::{AccountId32, BuildStorage}; construct_runtime!( pub enum TestRuntime { System: frame_system, Points: crate::pallet, } ); impl crate::pallet::Config for TestRuntime { type RuntimeEvent = RuntimeEvent; } #[test] fn transfer_works() { new_test_ext().execute_with(|| { Points::<TestRuntime>::insert(1, 100); assert!(Pallet::<TestRuntime>::transfer( RuntimeOrigin::signed(1), 2, 30, ).is_ok()); assert_eq!(Points::<TestRuntime>::get(1), 70); assert_eq!(Points::<TestRuntime>::get(2), 30); }); } }execute_with把测试代码放进一个全新的链上状态环境里执行，每次测试都是干净的账本。我对自己的要求是：任何 pallet 至少覆盖正常路径、余额不足、权限不足三种用例，因为这三类是链上最容易出安全事故的地方。
6. 我在实战中踩过最深的几个坑：升级、存储和共识
6.1 Runtime 升级的逻辑好改，存储迁移才是重头戏
这是我在 Substrate 上踩过最深的一个坑，没有之一。有次我给一个 pallet 增加了一个存储项，并且修改了某个已有存储项的数据结构，心想「只是加个字段而已」，于是直接调用了setCode升级 Runtime。链确实没停，交易也能跑，但老账本里的旧存储字段在读取时直接解码失败，那一瞬间我明白了什么叫Decode错误。
Substrate 的升级机制只负责把新的 Runtime 逻辑放到链上，它不会替你迁移数据。如果你改动了存储项的编码格式，旧数据在新代码里读不出来，就会导致该存储相关的所有交易全部失败。正确的做法是：在改动存储结构的同时，通过OnRuntimeUpgrade钩子写迁移逻辑，遍历旧数据、转换成新格式并重新写入。
具体来说，在 pallet 里定义：
#[pallet::hooks] impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> { fn on_runtime_upgrade() -> Weight { // 在这里执行存储迁移 Weight::zero() } }这段代码会在 Runtime 升级后、第一个区块执行前运行。把迁移写在这里，它会被包含进新 Runtime 的逻辑里，随着升级自动执行。我还建议上线前用try-runtime工具在链下快照里模拟执行迁移，这个工具会直接告诉你迁移是否会失败、影响多少存储项，比在测试网反复试错快得多。
6.2 StorageValue 的默认值陷阱：ValueQuery 不等于真的存了值
StorageValue<_, u32, ValueQuery>读取一个不存在的 key 时，返回的是0。这个设计很好用，但也坑人。有一次我升级代码，把一个ValueQuery存储改成OptionQuery，想着只是「少了个默认值」，结果老数据里如果本来就没有这个 key，新代码读到None，逻辑判断就变了。
更隐蔽的是，ValueQuery的默认值只是代码层面的读取结果，它不会在存储里真的写入任何东西。如果你在on_runtime_upgrade里检查存储是否存在，并按「不存在」做某件事，那么所有从未被初始化过的 key 都会被命中。这在初始化逻辑、合约账户创建这类场景下尤其容易出 bug。要判断存储项是否存在，永远用get返回的 Option 或者contains_key，不要依赖默认值做存在性判断。
6.3 共识配置：开发模式和生产模式最好别混用
我在本地跑--dev的时候，默认用的是 Aura 加 Grandpa。Aura 负责出块，Grandpa 负责最终确认。对于单节点开发环境，这套配置没问题，高可用性测试就露馅了：如果唯一的验证者节点挂了，整条链就停了，这是 PoA 机制的正常行为，不是 bug。
我后来做多节点测试时，踩了一个很经典的配置坑：我把 Aura 的 slot 时长调得过短，发现不同节点的区块时间戳经常错位，节点间频繁出现即时分叉又回滚。共识参数这种东西，看起来只是几个数字，实际影响的是全网的性能和稳定性。我的建议是，开发期用--dev默认值快速迭代，上线前再认真对着生产网络模板调共识参数，千万不要在开发链上调出一套奇怪参数，然后又把它原样搬到测试网。
6.4 日志、存储键和编译错误：排错三板斧
最后分享三个排错习惯，都是我交了学费学到的。
第一，调高日志级别。启动节点时用：
RUST_LOG=runtime=debug,pallet_points=trace ./target/release/node-template --dev这能在日志里看到 Runtime 内部流程，尤其是你的 pallet 里frame_support::log的输出。第二，用 Polkadot.js 的存储查询直接查看原始存储值，而不是靠猜。有一次我怀疑存储写入没生效，一查发现交易根本没执行成功，事件里躺着ExtrinsicFailed，根因是余额不足。第三，编译错误不要硬读宏展开信息，先缩小范围。FRAME 的宏会在construct_runtime!处展开大量代码，报错位置经常和你真正写错的地方不在同一行。我的做法是把刚加的 pallet 从construct_runtime!里注释掉，如果编译恢复，问题就锁定在那个 pallet 的类型约束上。
回看我做 Substrate 开发的这段路程，最深的体会是：它确实不是一个「三天上手」的工具，你至少要花几周和编译器、宏体系、类型系统混个脸熟。但一旦过了那个坎，你能在自己完全掌控的链上做任何定制，这种自由度是智能合约开发永远给不了的。如果你正在犹豫要不要入坑，我的建议很简单：先把模板跑起来，再抄一个最小 pallet 进去，感受一下从改代码到链上出块的完整链路，比看十篇博客都管用。
