区块链+IPFS去中心化文件存储DApp：链上索引与IPFS上传实战

简介：这是一份面向区块链与分布式存储方向学习者、Web3 前端开发者的实战项目源码，基于以太坊、Solidity、Web3.js、React.js 与 IPFS 构建类 Dropbox 的去中心化文件存储平台。项目用 Solidity 智能合约管理文件上传、权限控制与交易记录，前端通过 Web3.js 与合约交互，文件本体存入 IPFS 并按哈希写入链上，兼顾不可篡改与分发效率，适合想打通合约编写、前端调用与分布式存储全链路的进阶练习。资源包共 26 个文件、约 1.23MB，以 js 前端逻辑与 json 配置为主，辅以两个 sol 合约、truffle 迁移脚本、contracts 与 components 模块、测试用例及 env 示例、README 等，目录清晰便于按层阅读。已有 335 人学习，可据此复现完整项目结构、理解合约与界面协作方式，并积累链上存储场景的排错思路。

1. 一次传到 80% 崩掉的尴尬，先看清这个平台解决什么

「传到 80% 浏览器崩了，重传一次从头再来」——小团队互传资料时，这类糟心事几乎每周都遇上。这个用区块链和 IPFS 构建的去中心化文件存储平台，思路很直接：文件本身交给 IPFS 做内容寻址，文件名、类型、大小、CID、归属人写进链上合约，前端用 JavaScript 把 React 和 Web3.js 串起来。它对外就是一个网盘的样子，能上传、能列表、能共享、能删除；对内则把「谁拥有哪个文件、谁能看」这件事交给链上记账，不再依赖一台中心服务器说了算。想拿一个完整 DApp 练手的前端，和想弄清「链上存索引、链下存内容」这条边界到底该画在哪的开发者，都能从这个结构里拿到东西。

2. 技术栈与架构分工：一次上传要穿过哪四层

先给结论：这类项目最容易翻车的地方不是某段代码写错，而是把该放链下的东西塞到了链上。所以看架构时，重点盯的不是「用了什么框架」，而是「每一层各自维护什么状态」。

2.1 四层各自守哪块地盘

从上到下拆，一次「上传文件」实际要穿过四个角色。React 只负责界面和流程编排，它不知道区块链长什么样；Web3.js 负责把方法名和参数编码成 ABI 调用、把交易塞给钱包签名；Solidity 合约负责保存索引和权限映射，是唯一的「真相来源」；IPFS 负责真正的内容寻址存储，返回一个 CID，这个 CID 就是链上唯一需要记住的东西。

为什么不让文件直接上链？算一笔粗账就清楚了：一个 100KB 的文档如果拆成 32 字节的字写入合约存储，光存储开销就是三千多个槽位，成本高到没法用；而且文件内容一旦上链就永远删不掉，「删除文件」这个功能直接失效。反过来，CID 只有几十个字符，几个字符串字段加上地址和时间戳，一次上传的存储开销完全可控。

提示：这套分工的关键词是「链上存指针，链下存内容」。后面所有功能扩展，只要能守住这条线，架构就不会塌。

2.2 目录结构与依赖清单

项目按「合约侧」和「客户端侧」分成两棵树，这是 Web3.js 时代最常见也最好维护的布局。合约和前端各自有 package.json，避免把编译工具链的依赖灌进前端打包结果里。

decentralized-file-storage/ ├── contracts/ │ └── FileStorage.sol # 唯一的业务合约，索引 + 权限 ├── migrations/ │ └── 2_deploy_file_storage.js # 部署脚本 ├── test/ │ └── file_storage.test.js ├── truffle-config.js # 本地链网络配置 ├── package.json # 合约侧依赖 └── client/ ├── public/ ├── src/ │ ├── abis/ │ │ └── FileStorage.json # 编译产物，含 abi 和 networks │ ├── services/ │ │ ├── ipfs.js # IPFS 上传/读取封装 │ │ └── contract.js # Web3 与合约实例 │ ├── context/ │ │ └── Web3Context.js # 全局账户与合约状态 │ ├── components/ │ │ ├── FileUpload.js │ │ ├── FileList.js │ │ └── ShareModal.js │ └── App.js └── package.json

客户端依赖里，web3用 1.8.x 这一代最稳，因为合约调用写法、事件订阅、getAccounts的返回形态在 4.x 上有变化，混着抄代码必踩坑。ipfs-http-client建议锁到 60 附近的版本，再往上add的入参形态改过一轮，网上老教程直接传 File 对象会报类型错误。路由用react-router-domv6，组件里的useNavigate替代了老版本的history.push。

// client/package.json 里真正干活的几个依赖 { "dependencies": { "react": "^18.2.0", "react-router-dom": "^6.14.0", "web3": "^1.8.2", "ipfs-http-client": "^60.0.1" } }

根目录的truffle-config.js只需要关心一件事：本地链的端口和 network_id 要和钱包里配的网络对上。很多「合约明明部署了但前端读不到」的问题，根子就在这几十行。

// truffle-config.js module.exports = { networks: { development: { host: "127.0.0.1", port: 7545, // 本地链 RPC 端口 network_id: 1337, // 与本地链 chainId 对齐，对不上前端会找不到合约 }, }, compilers: { solc: { version: "0.8.17" }, }, };

把整条链路串起来看：用户在 React 里选文件，services/ipfs.js把字节流推到本地 IPFS 节点拿到 CID，services/contract.js拿到合约实例，调用uploadFile(name, type, size, cid)，钱包弹窗签名，交易上链后合约写入结构体并抛事件，React 收到回执后重新拉一次列表。整条链路上只有 CID 是「跨越」了链下和链上的东西，其余状态各归各层。

3. 合约层拆解：Solidity 怎么把文件索引写到链上

合约是整个项目里唯一不常改的部分，也是最该一次写对的部分。它要回答三个问题：文件元数据长什么样、谁能对该文件做什么、前端怎么高效地把「我的文件」一次性取走。

3.1 File 结构体与两张权限映射

结构体字段的顺序不是随便排的。id和fileSize是定长类型，放前面；string是变长类型，放后面，打包时更省槽位。uploadedAt用block.timestamp写入，前端格式化展示即可，不要在合约里做时间计算。exists这个布尔位看起来多余，但它是后面「软删除 + 过滤」方案的关键，删掉它列表里就会冒出幽灵记录。

// SPDX-License-Identifier: MIT pragma solidity ^0.8.17; contract FileStorage { struct File { uint256 id; // 自增主键，从 1 开始 uint256 fileSize; // 字节数，前端做展示用 uint256 uploadedAt; // 区块时间戳 address uploader; // 归属人 string fileName; string fileType; // MIME，如 application/pdf string fileHash; // IPFS CID，链上唯一的内容指针 bool exists; // 软删除标记，删除后置 false } uint256 public fileCount; mapping(uint256 => File) private files; // id -> 元数据 mapping(address => uint256[]) private ownedFileIds; // 归属人 -> id 列表 mapping(uint256 => mapping(address => bool)) private access; // id -> 地址 -> 是否被共享 event FileUploaded(uint256 indexed id, address indexed uploader, string fileHash, string fileName); event FileShared(uint256 indexed id, address indexed to); event FileDeleted(uint256 indexed id, address indexed by); }

ownedFileIds这张映射的意义在于：前端拉「我的文件」时不需要遍历全表，直接拿自己的 id 数组，再按 id 去files里取结构体。这一步把 O(总文件数) 降到了 O(我的文件数)，在链上读虽然不是主要成本，但前端一次call拿回几千条空记录也是要命的。

3.2 upload、share 和 delete 的实现细节

上传方法只有校验、写入和抛事件三件事。校验别写太复杂，链上 revert 的 gas 是要用户掏的，require保留最关键的几条：CID 不能为空、文件名不能为空。共享方法用onlyOwner修饰器守住，避免越权把别人的文件分享出去。删除用软删除，保留记录但把exists置 false，这样历史 id 不会被后续上传复用。

modifier onlyOwner(uint256 _id) { require(files[_id].exists, "file not found"); require(files[_id].uploader == msg.sender, "not the owner"); _; } function uploadFile( string memory _name, string memory _type, uint256 _size, string memory _hash ) public returns (uint256) { require(bytes(_hash).length > 0, "empty cid"); require(bytes(_name).length > 0, "empty name"); fileCount += 1; uint256 id = fileCount; files[id] = File(id, _size, block.timestamp, msg.sender, _name, _type, _hash, true); ownedFileIds[msg.sender].push(id); emit FileUploaded(id, msg.sender, _hash, _name); return id; } function shareFile(uint256 _id, address _to) public onlyOwner(_id) { require(_to != address(0), "zero address"); require(_to != msg.sender, "cannot share to self"); access[_id][_to] = true; emit FileShared(_id, _to); } function revokeShare(uint256 _id, address _to) public onlyOwner(_id) { access[_id][_to] = false; } function deleteFile(uint256 _id) public onlyOwner(_id) { files[_id].exists = false; emit FileDeleted(_id, msg.sender); }

参数校验里有个容易被忽略的点：_size由前端传入，链上无法验证真实性。这是这套架构的固有妥协——合约信任前端上报的元数据，真正的完整性由 IPFS 的 CID 保证，任何人拿到 CID 都能验证内容有没有被篡改。想更严一点，可以在合约里存 CID 的 keccak256 哈希而不是原字符串，省一点存储，代价是前端要做一次哈希计算。

3.3 查询方法怎么避开「返回结构体数组」的坑

getMyFiles是全篇最容易写出 DApp 前后端不一致的方法。ownedFileIds[msg.sender]里包含了已删除的 id，所以要先数一遍有效数量，再按数量 new 一个定长数组，最后逐个填充。顺序不能反，Solidity 里动态数组没法先 push 再返回。

function getMyFiles() public view returns (File[] memory) { uint256[] storage ids = ownedFileIds[msg.sender]; uint256 valid; for (uint256 i = 0; i < ids.length; i++) { if (files[ids[i]].exists) valid++; } File[] memory out = new File[](valid); uint256 k; for (uint256 i = 0; i < ids.length; i++) { if (files[ids[i]].exists) out[k++] = files[ids[i]]; } return out; } function getSharedFiles() public view returns (File[] memory) { uint256 valid; for (uint256 i = 1; i <= fileCount; i++) { if (files[i].exists && access[i][msg.sender]) valid++; } File[] memory out = new File[](valid); uint256 k; for (uint256 i = 1; i <= fileCount; i++) { if (files[i].exists && access[i][msg.sender]) out[k++] = files[i]; } return out; }

getSharedFiles不得不全表扫描，因为「分享给谁」的映射方向是id -> 地址，没法从地址反查。这是刻意的取舍：共享文件通常远少于总文件数，而且这是个view方法，不消耗 gas，只是请求耗时随总量线性增长。如果以后总量上千，正确做法是加一张mapping(address => uint256[]) sharedToMe反向索引，在shareFile里同步写入。

注意：File[] memory通过 ABI 返回时，Web3.js 拿到的是「按字段顺序排列的数组」，不是带字段名的对象。这一点在下一章的前端代码里会专门处理，别等运行起来才发现f.fileName永远是 undefined。

4. 前端链路：IPFS 上传与 Web3.js 合约调用怎么对接

前端是这套项目里改动最频繁的部分，也是新手最容易写成「一坨」的地方。合理的切法是三个文件：ipfs.js只管字节流，contract.js只管链，组件只管交互。任何一层跨层调用，后面加功能都会还债。

4.1 IPFS 上传封装：从 File 对象到 CID

浏览器里的File对象不是 Uint8Array，直接丢给ipfs.add时不同版本表现不一致，稳妥做法是先转成Uint8Array。上传成功后返回的是 CID 对象，必须.toString()才能存进合约的string字段，直接存对象会在 ABI 编码阶段报错。

// client/src/services/ipfs.js import { create } from 'ipfs-http-client'; // 本地节点默认 API 端口 5001，网关端口 8080 const ipfs = create({ host: 'localhost', port: 5001, protocol: 'http' }); export async function uploadToIPFS(file, onProgress) { const buffer = await file.arrayBuffer(); const added = await ipfs.add(new Uint8Array(buffer), { pin: true, // 主动 pin，避免本地节点垃圾回收把块清掉 progress: (bytes) => onProgress && onProgress(bytes), }); return added.cid.toString(); // 形如 Qm... 或 bafy... } // 预览/下载走本地网关，刚上传的块在公共网关上可能还没被索引 export function ipfsGatewayUrl(cid) { return `http://localhost:8080/ipfs/${cid}`; }

pin: true这个参数别省。本地 IPFS 节点默认会对新上传的块做临时 pin，但节点重启或手动执行 GC 后可能被清掉，那时用户在列表里点下载就是 404，排查半天还以为合约存错了。上传进度回调直接接到 React 的useState上，几十兆的文件至少让用户看到进度条在动。

4.2 合约实例与读写分离

contract.js干两件事：拿到 Web3 实例和账户，拿到当前网络下的合约实例。网络 id 一定要从链上实时查，不能写死，因为本地链重启后部署地址会变。

// client/src/services/contract.js import Web3 from 'web3'; import FileStorageArtifact from '../abis/FileStorage.json'; export async function initWeb3() { let web3; if (window.ethereum) { web3 = new Web3(window.ethereum); await window.ethereum.request({ method: 'eth_requestAccounts' }); } else { // 没装钱包插件时回落到本地链，方便纯调试界面 web3 = new Web3('http://127.0.0.1:7545'); } const accounts = await web3.eth.getAccounts(); return { web3, account: accounts[0] }; } export async function getContract(web3) { const networkId = await web3.eth.net.getId(); const deployed = FileStorageArtifact.networks[networkId]; if (!deployed) { throw new Error(`合约未部署到网络 ${networkId}，请检查迁移是否成功`); } return new web3.eth.Contract(FileStorageArtifact.abi, deployed.address); }

读和写必须分开看。读操作走.call()，不花 gas、不弹窗、即时返回；写操作走.send()，要签名、要等区块确认、会失败。新手最常见的写法是把getMyFiles也写成.send()，结果每次都弹一次钱包，用户以为程序坏了。

4.3 React 侧：上传组件与列表渲染

上传组件的动作顺序是固定的：先 IPFS，再上链。IPFS 失败就根本不该发交易，因为发出去的交易里没有 CID 可存，只能白白烧 gas。

// client/src/components/FileUpload.js（核心片段） import { useState } from 'react'; import { uploadToIPFS } from '../services/ipfs'; export default function FileUpload({ contract, account, onUploaded }) { const [busy, setBusy] = useState(false); async function handleFile(e) { const file = e.target.files[0]; if (!file || !contract) return; setBusy(true); try { const cid = await uploadToIPFS(file); await contract.methods .uploadFile(file.name, file.type || 'application/octet-stream', file.size, cid) .send({ from: account, gas: 600000 }); // 字段多，留足 gas onUploaded(); } catch (err) { console.error('upload failed', err); // 用户拒绝签名也走这里 } finally { setBusy(false); } } return <input type="file" onChange={handleFile} disabled={busy} />; }

列表组件要处理前面埋的那个雷：结构体数组解出来是下标数组。写一个归一化函数，同时兼容「带字段名」和「纯数组」两种形态，换 Web3.js 版本时不用重写渲染逻辑。

// client/src/components/FileList.js（核心片段） function normalize(raw) { return { id: raw.id ?? raw[0], fileSize: Number(raw.fileSize ?? raw[1]), uploadedAt: Number(raw.uploadedAt ?? raw[2]) * 1000, uploader: raw.uploader ?? raw[3], fileName: raw.fileName ?? raw[4], fileType: raw.fileType ?? raw[5], fileHash: raw.fileHash ?? raw[6], }; } export async function loadMyFiles(contract, account) { const raw = await contract.methods.getMyFiles().call({ from: account }); return raw.map(normalize); }

时间戳乘 1000 是因为合约里存的是秒级 Unix 时间，new Date()要毫秒。这类单位不一致不会报错，只会让列表里的日期显示成 1970 年，属于典型的「功能没错但看起来像坏了」。

5. 跑通与避坑排查：本地链、IPFS 节点和钱包的五个翻车点

整套环境有四个需要同时活着的进程：本地链、IPFS 节点、合约编译迁移、前端开发服务器。任何一个没起来，症状都很像，所以启动顺序要固定。

5.1 启动顺序与最小验证

先起链，再起 IPFS，然后迁移合约，最后起前端。每一步都有可验证的信号，别一口气全启动再去猜哪里错了。

# 终端 A：本地链，固定 chainId 便于钱包配置 ganache --wallet.deterministic --chain.chainId 1337 # 终端 B：IPFS 节点 ipfs init ipfs config Addresses.API /ip4/0.0.0.0/tcp/5001 ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080 ipfs daemon # 终端 C：编译并迁移合约 npm install truffle compile truffle migrate --network development --reset # 终端 D：前端 cd client && npm install && npm start

最小验证只做三件事：浏览器访问http://localhost:8080/ipfs/<随便一个刚上传的 CID>能看到内容，说明 IPFS 通了；truffle console里await instance.fileCount()返回非零，说明合约通了；前端页面上传一个小文本文件，列表里出现一行，说明整条链路通了。这三步任何一步过不去，都别急着改代码，先定位是哪一层没起来。

5.2 五条踩坑记录

一、合约迁移成功，前端报「合约未部署到网络 5777」现象是刷新页面就抛错，合约地址读不到。原因是钱包插件使用的网络 id 和迁移写入的网络 id 不是一个，build/contracts/*.json的networks字段里只有迁移时那个网络。解决方式是本地链固定chainId，钱包里手动添加同一个 RPC 和 id，然后重新truffle migrate --reset，让产物里的 networks 键对得上。

二、CID 拿到了，公共网关打开是 404现象是https://ipfs.io/ipfs/<cid>打不开，但合约里明明有值。原因是刚上传的块只存在于你的本地节点，公共网关还没索引到。解决方式是先用本地网关http://localhost:8080/ipfs/<cid>验证，确认块在本地；要长期可用就保持pin: true并保证节点常在线，或者接一个自己的固定网关。

三、列表渲染出来全是 undefined现象是files.map(f => f.fileName)一列空白。原因是 ABI 解码 tuple 时给的是下标数组，不带字段名。解决方式是写一个归一化函数按下标取值，别在渲染层直接点字段。这个坑和 Web3.js 版本关系不大，老版本新版本都一样。

四、点删除没反应，或者报 "not the owner"现象是交易直接 revert。原因通常有两个：钱包当前选中的账户不是上传者（切换过账户忘了切回来），或者把写方法当成了读方法。解决方式是所有写操作显式传from: account，并且 UI 上把当前账户地址显示出来，让用户知道自己是谁。

五、超过几兆的文件上传失败或浏览器卡死现象是进度条卡住，或者交易发出后一直 pending。原因是整个文件被arrayBuffer读进内存，同时合约一次写入多个变长字符串，gas 估算偏差会导致交易失败。解决方式是上传前限制文件大小，给send显式指定足够的gas，更大的文件改成分片上传、只把最终 CID 上链。

提示：这五条里前三条属于配置和 ABI 层面，改起来快；后两条属于架构层面的成本约束，改起来要动设计。先分清是哪一类，再决定要不要动代码。

6. 二次开发：把这个网盘改成你自己要的样子

跑通之后，真正有意思的是改造。我按投入产出比排了三个方向，从最轻到最重。

第一个方向是加密后再上传。现在的实现里，任何拿到 CID 的人都能从网关取到文件内容，共享只是「链上记录谁被允许看」，并没有真正的内容保护。改造思路是在uploadToIPFS之前用对称密钥加密字节流，只把密文的 CID 上链，密钥用被分享人的公钥加密后写进合约的另一个映射里。合约加一个mapping(uint256 => mapping(address => bytes)) encryptedKeys，shareFile的时候顺带写入。这样即使 CID 泄露，没有私钥也解不开。

第二个方向是把元数据查询从链上挪走。现在getSharedFiles是全表扫描，文件数上去以后前端会很慢。常见做法是用事件做索引：合约里已经有FileUploaded、FileShared、FileDeleted三个事件，写一个 JavaScript 脚本从部署区块开始把事件全捞出来，在本地或一个轻量服务里维护一份可查询的视图，前端只查这份视图，需要校验时再回链上核对。代码量不大，但能把列表页的响应从秒级降到毫秒级。

// scripts/indexEvents.js —— 从事件重建一份本地索引，用于校验链上与 UI 是否一致 const events = await contract.getPastEvents('FileUploaded', { fromBlock: 0, toBlock: 'latest', }); const index = new Map(); for (const e of events) { index.set(e.returnValues.id, { uploader: e.returnValues.uploader, fileHash: e.returnValues.fileHash, fileName: e.returnValues.fileName, }); } console.log(`索引到 ${index.size} 条上传记录`);

这段脚本我一般当回归测试用：UI 上看到几条，索引里就该有几条。数字对不上，基本就是漏了某个事件或者分页没拉全。

第三个方向是给文件加版本链。现在同名文件重复上传会变成两条独立记录，没有「历史版本」的概念。改法是把File拆成FileMeta（当前指针）和FileVersion（历史记录），uploadFile时如果同名就新增一个版本并把当前指针指向最新 CID。这个改动会牵动合约、前端列表和共享逻辑，属于「跑通之后想做产品化」才值得动的部分。

有一点是我踩过之后才养成的习惯：每加一个新方法，先在truffle console里手动调一遍，确认返回值形态、事件参数、gas 消耗都符合预期，再去写 React 组件。前端调试的成本远高于控制台，链条上任何一处不对，在浏览器里都会被包装成一句「交易失败」，难看又难查。从那以后我每次改合约，都强制走一遍「控制台验证 → 前端接入 → 事件对账」这三步，省下来的时间比写代码多得多。希望这套拆解能帮你把它跑起来，也改成你想要的样子。

本文还有配套的精品资源，点击获取