从零到一：我在Solana NFT铸造前端中搞定@solana/web3.js连接与交易

竹林818
3 阅读1分钟

背景：从以太坊“舒适区”闯入Solana

最近公司要开拓新链，启动了一个Solana生态的NFT项目，我被分配负责前端DApp的开发。作为一个有几年以太坊开发经验的“老兵”，我起初信心满满，心想不就是换条链、换个库嘛，ethers.js换成@solana/web3.js，MetaMask换成Phantom，能有多难？

我的第一个任务是实现最基础的功能：连接Phantom钱包，并让用户能支付SOL来铸造一个NFT。我照搬了以太坊的思路：安装库、找连接钱包的示例代码、组装交易。结果从第一步开始就处处碰壁。控制台里满是“WalletNotConnectedError”、“Transaction构造失败”、“BlockhashNotFoundError”这类错误。我意识到，Solana的开发范式和我熟悉的以太坊有根本性的不同，必须放下经验，从头梳理。这篇文章，就是我填平这个认知鸿沟的实战记录。

问题分析：为什么我的“以太坊思维”不灵了？

一开始，我试图快速搭建一个原型。我安装了@solana/web3.js和@solana/wallet-adapter系列库，复制了一段网上找到的钱包连接代码。界面很快出来了，点击“连接钱包”也能弹出Phantom。

问题出现在下一步：发送交易。在以太坊里，我习惯用signer.sendTransaction(tx)一气呵成。但在Solana里，我看到的例子都是先构造一个Transaction对象，然后添加指令（Instruction），最后用钱包签名并发送。我照猫画虎写了一段，点击“铸造”后，要么交易直接失败，要么钱包弹出了签名窗口但交易迟迟不上链。

经过一番排查和阅读文档，我发现了几个关键差异点，这也是我后续解决问题的核心：

  1. 交易模型不同：以太坊交易是“账户-账户”的，而Solana交易是“指令（Instruction）的集合”，一个交易可以包含多个涉及不同程序的指令。我需要先理解如何构造正确的指令。
  2. 状态管理：Solana交易需要包含一个最近的blockhash作为“门票”，用来防止重放攻击，并且这个blockhash有过期时间。我必须动态地从RPC节点获取它。
  3. 费用支付者（Fee Payer）：在Solana中，支付交易费用的账户（通常是用户钱包）必须在交易中明确指定，并且需要作为签名者之一。
  4. 前后端职责：NFT铸造的核心逻辑（比如找到正确的程序ID、构造铸造指令）通常由后端或SDK完成，前端主要负责组装、签名和发送。我需要与后端同事确认指令的生成方式。

理清了这些，我才明白不能直接硬套代码，必须分步骤把每个环节打通。

核心实现步骤

第一步：搭建环境与基础钱包连接

首先，我创建了一个新的React + TypeScript项目，并安装核心依赖。

npm install @solana/web3.js @solana/wallet-adapter-wallets @solana/wallet-adapter-react @solana/wallet-adapter-react-ui @solana/wallet-adapter-base

这里我选择了@solana/wallet-adapter这个社区维护的钱包适配器套件，它封装了连接不同钱包的复杂逻辑，用起来比直接操作window.solana要省心很多。

我的组件结构如下：用一个WalletProvider包裹整个应用，然后在需要的地方使用useWallet钩子来获取钱包状态和连接方法。

// App.tsx
import React from 'react';
import { ConnectionProvider, WalletProvider } from '@solana/wallet-adapter-react';
import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import { PhantomWalletAdapter } from '@solana/wallet-adapter-wallets';
import { WalletModalProvider } from '@solana/wallet-adapter-react-ui';
import { clusterApiUrl } from '@solana/web3.js';
import HomePage from './pages/Home';

// 导入默认样式
import '@solana/wallet-adapter-react-ui/styles.css';

function App() {
  // 配置网络。开发时可以用devnet，上线用mainnet-beta
  const network = WalletAdapterNetwork.Devnet;
  const endpoint = clusterApiUrl(network);

  // 配置支持的钱包，这里只用了Phantom
  const wallets = [new PhantomWalletAdapter()];

  return (
    <ConnectionProvider endpoint={endpoint}>
      <WalletProvider wallets={wallets} autoConnect>
        <WalletModalProvider>
          <HomePage />
        </WalletModalProvider>
      </WalletProvider>
    </ConnectionProvider>
  );
}

export default App;

这里有个坑：@solana/wallet-adapter-react-ui的样式需要单独引入，否则连接按钮会没有样式。另外，autoConnect属性可以尝试自动重新连接上次用过的钱包，提升用户体验。

第二步：获取连接实例与关键信息

在铸造页面，我需要获取几个关键对象：

  1. connection: 与Solana集群通信的入口。
  2. publicKey: 当前连接钱包的地址。
  3. signTransaction: 钱包提供的签名方法。
// pages/Home.tsx
import React, { useState } from 'react';
import { useConnection, useWallet } from '@solana/wallet-adapter-react';
import { PublicKey, Transaction, SystemProgram, LAMPORTS_PER_SOL } from '@solana/web3.js';

const HomePage: React.FC = () => {
  const { connection } = useConnection();
  const { publicKey, signTransaction, connected } = useWallet();
  const [loading, setLoading] = useState(false);
  const [status, setStatus] = useState('');

  // ... 其他逻辑

  return (
    <div>
      <div>钱包状态: {connected ? `已连接 (${publicKey?.toBase58()})` : '未连接'}</div>
      {/* 使用 WalletMultiButton 来自 wallet-adapter-react-ui */}
      {/* 铸造按钮和状态显示 */}
    </div>
  );
};

有了这些，我就具备了发送交易所需的所有“工具”。

第三步：动态获取Blockhash并构造交易

这是最核心也最容易出错的一步。我写了一个createMintTransaction函数来模拟构造交易的过程。在实际项目中，mintInstruction应该由后端API根据当前铸造规则生成。

const createMintTransaction = async (
  payerPublicKey: PublicKey,
  connection: Connection
): Promise<Transaction> => {
  // 1. 创建空交易对象
  const transaction = new Transaction();

  // 2. 设置交易的支付费用者（Fee Payer）—— 这是必须的！
  transaction.feePayer = payerPublicKey;

  // 3. 获取最新的blockhash和lastValidBlockHeight。
  // **注意这个细节**：blockhash会过期，必须每次发送交易前重新获取。
  const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
  transaction.recentBlockhash = blockhash;
  // lastValidBlockHeight 可用于后续查询交易状态时的超时判断

  // 4. 添加指令（Instructions）。
  // 这里是一个模拟的“支付1 SOL到系统地址”的指令，仅用于演示交易流程。
  // 真实的NFT铸造指令会复杂得多，涉及Token Program和Metadata Program。
  const demoInstruction = SystemProgram.transfer({
    fromPubkey: payerPublicKey,
    toPubkey: new PublicKey('11111111111111111111111111111111'), // 系统地址
    lamports: LAMPORTS_PER_SOL * 1, // 1 SOL
  });
  transaction.add(demoInstruction);

  // 在实际项目中，指令可能来自后端：
  // const mintInstruction = await fetchMintInstructionFromBackend(payerPublicKey);
  // transaction.add(mintInstruction);

  return transaction;
};

踩坑重点：我一开始把getRecentBlockhash的结果缓存起来，想着重复使用能减少RPC调用。结果用户过几分钟再操作时，交易总是失败，提示BlockhashNotFoundError。原来Solana的blockhash是有生命周期的（约2分钟），必须为每一笔新交易获取最新的。

第四步：签名并发送交易

交易构造好后，需要用户的钱包进行签名，然后发送到网络。

const handleMint = async () => {
  if (!publicKey || !signTransaction) {
    setStatus('请先连接钱包');
    return;
  }

  setLoading(true);
  setStatus('准备交易...');

  try {
    // 1. 构造交易
    setStatus('构造交易中...');
    const transaction = await createMintTransaction(publicKey, connection);

    // 2. 让钱包签名交易
    // **这里有个坑**：signTransaction方法接收的是Transaction对象，返回的是签名后的版本。
    setStatus('请在钱包中确认签名...');
    const signedTransaction = await signTransaction(transaction);

    // 3. 发送已签名的交易
    setStatus('发送交易中...');
    const rawTransaction = signedTransaction.serialize(); // 序列化成字节
    const txid = await connection.sendRawTransaction(rawTransaction, {
      skipPreflight: false, // 设置为true可跳过预检加速，但失败不返Gas费
      preflightCommitment: 'confirmed',
    });

    setStatus(`交易已发送! TXID: ${txid}`);

    // 4. 确认交易
    setStatus('等待网络确认...');
    const confirmationStrategy = {
      signature: txid,
      blockhash: transaction.recentBlockhash!,
      lastValidBlockHeight: (await connection.getLatestBlockhash('confirmed')).lastValidBlockHeight,
    };

    const result = await connection.confirmTransaction(confirmationStrategy, 'confirmed');
    if (result.value.err) {
      setStatus(`交易确认失败: ${JSON.stringify(result.value.err)}`);
    } else {
      setStatus('🎉 交易成功确认！');
    }
  } catch (error: any) {
    console.error('铸造失败:', error);
    setStatus(`错误: ${error.message}`);
  } finally {
    setLoading(false);
  }
};

关键点：signTransaction是钱包适配器提供的方法，它会触发钱包（如Phantom）的弹窗，让用户查看交易详情并签名。发送时使用sendRawTransaction，并可以选择是否进行预检（preflight）。最后，使用confirmTransaction并传入之前获取的blockhash信息来等待交易最终上链，这是一种更可靠的确认方式。

完整代码示例

以下是一个整合了以上所有步骤的简化版可运行组件：

// pages/Home.tsx
import React, { useState } from 'react';
import { useConnection, useWallet } from '@solana/wallet-adapter-react';
import { WalletMultiButton } from '@solana/wallet-adapter-react-ui';
import { PublicKey, Transaction, SystemProgram, LAMPORTS_PER_SOL, Connection } from '@solana/web3.js';

const HomePage: React.FC = () => {
  const { connection } = useConnection();
  const { publicKey, signTransaction, connected } = useWallet();
  const [loading, setLoading] = useState(false);
  const [status, setStatus] = useState<string>('');

  const createMintTransaction = async (payerPublicKey: PublicKey): Promise<Transaction> => {
    const transaction = new Transaction();
    transaction.feePayer = payerPublicKey;

    const { blockhash } = await connection.getLatestBlockhash('confirmed');
    transaction.recentBlockhash = blockhash;

    // 演示指令：转账1 SOL到系统地址
    const demoInstruction = SystemProgram.transfer({
      fromPubkey: payerPublicKey,
      toPubkey: new PublicKey('11111111111111111111111111111111'),
      lamports: LAMPORTS_PER_SOL * 1,
    });
    transaction.add(demoInstruction);
    return transaction;
  };

  const handleMint = async () => {
    if (!publicKey || !signTransaction) {
      setStatus('请先连接钱包');
      return;
    }
    setLoading(true);
    setStatus('开始...');
    try {
      const transaction = await createMintTransaction(publicKey);
      setStatus('等待钱包签名...');
      const signedTx = await signTransaction(transaction);
      setStatus('发送交易...');
      const txid = await connection.sendRawTransaction(signedTx.serialize());
      setStatus(`交易已发送: ${txid}`);

      // 简单确认，实际项目应用更健壮的 confirmTransaction
      await connection.confirmTransaction(txid, 'confirmed');
      setStatus('🎉 交易成功！');
    } catch (error: any) {
      console.error(error);
      setStatus(`失败: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div style={{ padding: '2rem', fontFamily: 'sans-serif' }}>
      <h1>Solana NFT铸造演示</h1>
      <div style={{ marginBottom: '1rem' }}>
        <WalletMultiButton />
      </div>
      <div style={{ marginBottom: '1rem' }}>
        状态: {connected ? `已连接 (${publicKey?.toBase58().slice(0, 8)}...)` : '未连接'}
      </div>
      <button
        onClick={handleMint}
        disabled={!connected || loading}
        style={{
          padding: '0.75rem 1.5rem',
          fontSize: '1rem',
          backgroundColor: connected && !loading ? '#9945FF' : '#CCCCCC',
          color: 'white',
          border: 'none',
          borderRadius: '8px',
          cursor: connected && !loading ? 'pointer' : 'not-allowed',
        }}
      >
        {loading ? '处理中...' : '模拟铸造 (支付1 SOL)'}
      </button>
      {status && (
        <div style={{ marginTop: '1rem', padding: '1rem', backgroundColor: '#f0f0f0', borderRadius: '8px' }}>
          <strong>日志:</strong> {status}
        </div>
      )}
    </div>
  );
};

export default HomePage;

踩坑记录

  1. WalletNotConnectedError 但钱包已连接：我一开始在handleMint函数里直接使用useWallet()返回的signTransaction，但有时在异步回调中，这个引用会失效。解决方法是确保在触发用户交互（如点击按钮）的函数作用域内，直接从最新的钩子返回值中获取signTransaction和publicKey，或者使用useRef来保持最新引用。

  2. 交易发送成功但立即失败：错误信息是Transaction simulation failed。这通常是指令（Instruction）构造有问题，比如账户权限不对、数据格式错误。解决方法：仔细检查指令中每一个PublicKey参数是否正确，尤其是关联账户（PDA）的推导是否与程序端一致。利用connection.simulateTransaction(transaction)在发送前进行模拟，可以提前发现大部分逻辑错误。

  3. BlockhashNotFoundError：这是我踩得最久的一个坑。我为了“优化”，在应用启动时获取一次blockhash并缓存，所有用户交易都复用。结果交易总是失败。根本原因：Solana的blockhash有过期时间（约150个区块，2分钟）。必须为每一笔新交易调用connection.getLatestBlockhash()获取最新的。这是Solana安全模型的一部分，防止交易重放。

  4. Phantom钱包弹窗被浏览器拦截：在signTransaction被调用时，如果页面有快速的连续状态更新（比如频繁setState），可能会打断钱包的弹窗流程，甚至被浏览器当成弹窗广告拦截。解决方法：确保签名请求是直接由一次性的用户交互（如按钮点击）触发，并在等待签名期间保持UI稳定，避免不必要的重渲染。

小结

通过这个实战项目，我深刻体会到，从以太坊切换到Solana前端开发，绝不仅仅是替换一个SDK那么简单，核心是理解其账户模型和交易生命周期。最关键的一步是：为每一笔交易动态获取并设置最新的blockhash和feePayer。接下来，我可以继续深入Token Program、关联账户（PDA）推导、以及如何与Anchor框架编写的智能合约交互，这些都是构建复杂Solana DApp的必备技能。

avatar
文章
阅读
粉丝