把React应用部署到IPFS并配合Filecoin做持久化存储，是近年去中心化Web（DWeb）实践中非常典型的一套方案。传统部署方式依赖中心化服务器和域名解析，一旦服务器故障或者备案域名失效，应用就会完全不可访问。而IPFS基于内容寻址，文件的访问地址由内容哈希决定，只要网络中任意一个节点保存了这份文件，用户就能拿到完全一致的内容，天然具备抗审查和高可用的特性。本文将从原理、构建配置、部署流程和常见问题四个层面，完整讲解React应用迁移到IPFS + Filecoin的具体做法。
一、理解IPFS的内容寻址与React应用的兼容性问题
IPFS的核心思想是内容寻址（Content Addressing）。传统的Web使用位置寻址，比如 https://ippipp.com/index.html，资源通过“在哪里”来定位；而IPFS使用内容标识符CID（Content Identifier），通过SHA-256等哈希算法对文件内容计算摘要，资源通过“是什么”来定位。同一个CID在任何节点上取回的内容都完全相同，这也意味着内容一旦发布就不可篡改，任何修改都会产生新的CID。
这个特性对React应用提出了两个直接挑战。第一，路由问题。React应用常用React Router，默认使用BrowserRouter，依赖HTML5的History API。在IPFS上，应用是通过类似 /ipfs/QmHash/ 这样的路径访问的，不存在服务器端的路由重写配置，直接刷新子路由会返回404。第二，资源引用路径问题。构建产物中JS、CSS的引用路径如果以 / 开头，在IPFS网关下会解析到网关根路径而不是应用所在子路径，导致资源加载失败。
解决路由问题的标准做法是改用HashRouter，即把路由信息放在URL的hash部分（如 #/about），hash部分不会被发送到服务器，自然也就不依赖服务端重写规则。资源路径问题则需要在构建时把publicPath设置为相对路径 ./，让所有资源引用相对于index.html解析。
二、构建配置调整与产物结构优化
以Vite构建的React项目为例，需要调整vite.config.js中的base配置。如果是CRA（Create React App）创建的项目，对应的是package.json中的homepage字段。两者目的相同：让构建产物中的资源引用从绝对路径变为相对路径。
import { defineConfig } from 'vite'
import react from '@vitevitejs/plugin-react'
export default defineConfig({
plugins: [react()],
// 关键配置：使用相对路径，保证IPFS子路径下资源可正常加载
base: './',
build: {
outDir: 'dist'
}
})对CRA项目，只需在package.json中添加一行配置：
{
"name": "my-react-app",
"version": "0.1.0",
"homepage": ".",
"dependencies": {
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-router-dom": "^6.20.0"
}
}路由部分将BrowserRouter替换为HashRouter，这是迁移中最容易被遗漏的一步：
import React from 'react'
import ReactDOM from 'react-dom/client'
import { HashRouter, Routes, Route } from 'react-router-dom'
import App from './App'
import Home from './pages/Home'
import About from './pages/About'
ReactDOM.createRoot(document.getElementById('root')).render(
<HashRouter>
<Routes>
<Route path="/" element={<Home />} />
<Route path="/about" element={<About />} />
</Routes>
</HashRouter>
)除了路径和路由，还要检查代码中是否存在写死的绝对路径请求，比如 fetch('/api/data') 这类调用。在IPFS环境下这类路径会指向网关根目录，必须改为完整URL或相对路径。此外建议在public目录添加一个404.html并复制一份index.html的内容，作为部分网关的兜底方案。
三、上传到IPFS并通过Filecoin实现持久化存储
构建产物准备好之后，下一步是把dist目录上传到IPFS网络。本地开发可以用IPFS Desktop或ipfs-cli直接添加：
ipfs add -r dist # 输出中最后一条 added <CID> dist 即为整个目录的根CID
但仅仅本地ipfs add是不够的，只有你自己的节点存储了这些数据，节点下线数据就消失了。这时需要Pin（固定）机制和Filecoin的配合。Filecoin是建立在IPFS之上的激励层，存储提供者通过存储交易赚取FIL代币，从而保证数据被长期、可验证地存储。实际操作中最便捷的方式是使用封装了Filecoin存储交易的服务，例如web3.storage或Storacha，它们会自动帮你完成Pin和Filecoin交易撮合。
以命令行方式为例，安装w3cli工具后：
npm install -g @web3-storage/w3cli w3 login your-email@ipipp.com w3 space create react-app w3 up dist
w3 up命令会返回一个CID和一个 https://w3s.link/ipfs/... 形式的网关地址。执行完成后，数据不仅可以在IPFS网络上被检索，还会被自动打包成Filecoin存储交易，由多个存储提供者冗余保存，存储证明会被记录在Filecoin区块链上，任何人都可以验证数据确实被妥善存储。
拿到CID后，可以通过公共网关访问应用，例如 https://ipfs.io/ipfs/<你的CID>/。也可以绑定自定义域名，将DNS的TXT记录设置为 dnslink=/ipfs/<CID>，这样每次更新应用只需更新dnslink指向的新CID，域名访问入口保持稳定。
四、迁移后的数据更新、API请求与性能考量
IPFS的不可篡改特性带来一个必须正视的问题：应用如何更新？由于每次构建产物不同，CID必然变化，本质上每次发布都是一个“新应用”。常见的策略有三种：一是更新dnslink记录，让固定域名指向新CID；二是使用IPNS（InterPlanetary Name System），为内容生成一个可变的名称，IPNS名称解析到最新的CID；三是引入ENS等区块链域名做解析层。其中dnslink方案延迟最低，IPNS全球生效较慢但去中心化程度更高，需要根据业务场景权衡。
对于需要动态数据的React应用，还需要理清“前端去中心化”与“数据源”的关系。IPFS只能托管静态资源，API请求依然可以指向传统后端、或者指向智能合约、OrbitDB、Ceramic等去中心化数据协议。跨域方面，公共网关下的应用Origin与后端API不同，后端需要正确配置CORS响应头。建议把核心静态资源放在IPFS上，动态数据通过fetch请求获取，形成混合架构：
// 在IPFS托管的前端中请求后端API
async function loadUserData() {
const res = await fetch('https://api.ipipp.com/user/profile', {
headers: { 'Content-Type': 'application/json' }
})
if (!res.ok) throw new Error('网络请求失败')
return res.json()
}性能方面，公共网关的首次加载速度通常不如CDN，可以通过prefetch关键资源、压缩构建产物、使用Service Worker缓存等方式优化。同时要注意Filecoin存储交易从发起到链上确认需要一定时间窗口，重要数据建议在多个Pin服务之间做冗余，避免单点依赖。完成这些配置后，你的React应用就拥有了一个不依赖任何单一服务器的前端分发层，配合Filecoin的链上存储证明，整体可用性和抗风险能力都会比传统部署方式有实质提升。
IPFSFilecoinReact去中心化存储修改时间：2026-09-12 03:12:38