PeerTube的官方实现基于Angular，但前端框架的选型本身并不是分布式服务的硬性约束。借助Vue3的组合式API，你完全可以在熟悉的生态里搭出一套类PeerTube的去中心化视频平台。其核心难点在于如何把P2P传输、联邦宇宙（Fediverse）通信和视频播放器状态管理融入Vue3的工程体系。本文将带你从Vite脚手架开始，一步步实现一个可运行、可扩展的轻量级PeerTube工程。
整个方案采用分层思路：基础设施层负责网络传输，业务层通过组合式函数封装状态，用户界面层只关心渲染。这样设计的好处是，即便将来WebTorrent被更好的传输协议替代，你也可以无缝切换到新方案。
一、项目初始化与目录结构设计
工程化从项目骨架开始。使用Vite的vue-ts模板创建项目后，需要按照功能模块重新组织目录。默认的src目录结构过于简单，无法支撑PeerTube这种包含API请求、P2P连接、视频渲染的复杂应用。建议采用以下分层：
npm create vite@latest peertube-vue -- --template vue-ts cd peertube-vue npm install pinia vue-router webtorrent
创建完毕后，将src拆分为几个核心目录：api目录存放与PeerTube实例交互的HTTP客户端；composables目录集中管理可复用的组合式函数；stores目录放Pinia状态模块；components目录则按业务领域拆分子组件。此外还需要一个config目录，存放tracker服务器地址、实例发现地址等常量。
有了骨架，下一步是设置环境变量。开发环境需要本地Tracker，生产环境则需要指向公共Tracker。在.env.development文件中加入VITE_TRACKER_URL变量，并在axios封装中读取它。很多开发者习惯把API地址硬编码在代码里，这在去中心化架构下会带来麻烦，因为不同PeerTube实例的API地址各不相同，必须通过运行时配置或路由参数来决定调用哪个节点。
二、集成WebTorrent实现P2P流媒体传输
PeerTube的核心特点是使用BitTorrent协议分发视频，实现播放负载分散到每个观看者。WebTorrent是浏览器端的BitTorrent实现，它通过WebRTC数据通道（RTCPeerConnection）在浏览器之间直接传输数据，而不需要传统的TCP端口。要工程化地使用WebTorrent，不能把逻辑直接写在组件里，应该封装成组合式函数，让任何组件都能轻松调用流媒体能力。
// src/composables/useTorrent.ts
import { ref, onScopeDispose } from 'vue'
import WebTorrent from 'webtorrent'
export function useTorrent() {
const client = new WebTorrent()
const progress = ref(0)
const speed = ref(0)
const streamURL = ref('')
let currentTorrent: WebTorrent.Torrent | null = null
async function loadTorrent(magnetURI: string, fileIndex = 0) {
// 如果已有下载任务，先销毁
if (currentTorrent) currentTorrent.destroy()
// 开始下载种子
currentTorrent = client.add(magnetURI, (torrent) => {
const file = torrent.files[fileIndex]
// 将视频文件流式渲染到Blob URL
streamURL.value = file.streamURL ? file.streamURL() : URL.createObjectURL(file.blob)
torrent.on('download', () => {
progress.value = torrent.progress
speed.value = torrent.downloadSpeed
})
})
}
onScopeDispose(() => {
// 组件销毁时彻底清理连接
currentTorrent?.destroy()
client.destroy()
})
return { loadTorrent, progress, speed, streamURL }
}
这个组合式函数暴露出来的是响应式的进度、速度和最终播放地址。在浏览器中实际使用时会发现，直接调用file.streamURL()在某些WebTorrent版本里并不存在，而应该先获取Blob再通过URL.createObjectURL创建地址。为了避免这个坑，代码里做了兼容回退。另外，onScopeDispose必须在setup上下文中调用，确保组件卸载时不被残留的P2P连接拖垮浏览器。
实际使用时还应当注意Tracker服务器的配置。公共Tracker虽然方便，但由于WebRTC无法穿透某些对称型NAT，会出现少量用户无法成功连接。生产环境可以在自己的域名下部署Tracker，或者同时配置多个Tracker地址。连接情况直接影响播放首帧时间，建议在用户点击播放时直接调用loadTorrent，并提前展示“正在连接P2P网络”的状态提示。
三、Pinia状态管理与联邦通信
PeerTube不是单实例系统，它天然属于Fediverse网络，实例之间通过ActivityPub协议同步订阅关系、视频信息和用户状态。这就意味着前端状态中必须同时管理多个远端节点的数据。Pinia作为Vue3的官方状态库，很适合承担这层职责。与其他状态库相比，Pinia的组合式API风格与Vue3的依赖注入天然契合，没有Mutations的冗余概念，在异步分发上更直观。
// src/stores/instance.ts
import { defineStore } from 'pinia'
import axios from 'axios'
interface InstanceState {
currentNode: string
federatedTimeline: unknown[]
loading: boolean
}
export const useInstanceStore = defineStore('instance', {
state: (): InstanceState => ({
currentNode: '',
federatedTimeline: [],
loading: false
}),
actions: {
async fetchFederatedTimeline() {
this.loading = true
try {
// 从当前实例获取联邦时间线
const { data } = await axios.get(`${this.currentNode}/api/v1/video-channels/trending`)
this.federatedTimeline = data
} finally {
this.loading = false
}
}
}
})
联邦通信的难点并不在Pinia本身，而在于数据签名。ActivityPub标准要求每个动作都由发送方私钥签名，接收方用公钥验证。要在前端工程里完整支持这套机制，就需要引入OpenPGP.js等加密库，并在请求头加入Signature字段。对于大多数视频平台场景，可以先从只读的拉取开始，只验证响应数据完整性，不主动对外发送签名请求，这样工程复杂度会下降不少。
另外，跨实例请求经常会遇到CORS限制。PeerTube实例默认允许部分跨域读取，但如果你希望前端直接通过AJAX访问远程实例的API，仍需要在对方实例配置白名单。一个更简单的替代方案是使用自己的后端服务作为代理，前端只与外域实例通信，签名和CORS都由后端处理。这样前端Pinia逻辑不会被加密细节淹没，代码可读性更佳。
四、视频播放器组件与生命周期管理
播放器是视频平台的门面。直接把video标签与WebTorrent捆绑在一起会让组件变得极其臃肿，所以必须拆成一个独立的VideoPlayer子组件，通过Props接收streamURL，通过事件反馈播放状态。播放器的生命周期中，最关键的是停止播放时的资源释放。WebTorrent客户端如果一直在后台运行，会持续占用带宽和CPU，需要借助Vue3的watchEffect和onBeforeUnmount来控制。
<template>
<div class="video-player">
<video v-if="src" :src="src" controls autoplay @pause="emit('pause')" @ended="emit('ended')"></video>
<div v-else class="loading">正在连接P2P网络...</div>
</div>
</template>
<script setup lang="ts">
import { watchEffect, onBeforeUnmount } from 'vue'
const props = defineProps<{ src: string }>()
const emit = defineEmits(['pause', 'ended'])
watchEffect(() => {
// 依赖props.src变化，自动更新video状态
if (props.src) {
console.log('[player] stream URL updated')
}
})
onBeforeUnmount(() => {
// 释放潜在的媒体流
if (props.src && props.src.startsWith('blob:')) {
URL.revokeObjectURL(props.src)
}
})
</script>
这里有个容易被忽略的坑：当WebTorrent返回的是Blob URL时，组件卸载时必须调用URL.revokeObjectURL，否则会造成内存泄漏。对于常见的MP4格式，一般使用可续播的流式Blob；如果你需要精确控制码率和缓冲策略，可以考虑把下载到本地的Temporary Blob保存到IndexedDB，并在播放器初始化前恢复之前的播放进度。
在Vue3中还可以利用Teleport将全屏控制层渲染到body下，避免父级组件的overflow属性干扰全屏样式。将PlayerControls组件包在Teleport中，通过teleport属性指定“body”容器，再用v-if控制显隐。这样既保证结构清晰，又不会和登录弹窗等外层UI发生层级冲突。对于去中心化平台，播放器还应该展示当前视频来源的实例域名，让用户明确知道正在直接从哪个节点拉流。
五、工程化构建与部署优化
当项目体积随着视频渲染逻辑和加密库的引入逐渐增大时，必须对Vite构建配置做出调整。首要优化是路由懒加载，在vue-router中将每个页面组件改为动态导入。PeerTube的详情页包含视频播放器、评论区、相关推荐，所有内容都需要独立加载，这样可以做到只渲染当前用户需要的模块，首屏加载时间显著缩短。
// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
const routes = [
{
path: '/',
name: 'home',
component: () => import('../views/HomeView.vue')
},
{
path: '/watch/:videoId',
name: 'watch',
component: () => import('../views/WatchView.vue')
}
]
export default createRouter({
history: createWebHistory(),
routes
})
另一个必要步骤是使用vite-plugin-pwa将平台变成可安装的渐进式Web应用。视频类平台对断网耐受力要求非常高，至少要让用户在离线状态下看到之前缓存的视频列表。在vite.config.ts中加入VitePWA插件，配置manifest和Service Worker。注意要将WebTorrent的js文件列入precache名单，否则在线切换时P2P库会被重复加载。
部署到服务器上时，还需要处理Tracker服务的CSP（内容安全策略）。由于WebRTC会连接大量未知主机的WebSocket，默认的CSP规则会阻止所有非白名单连接。需要在静态服务器的响应头中添加connect-src规则，放宽对wss://和https://的限制。如果使用Nginx作为反代，可以这样配置：
location / {
add_header Content-Security-Policy "default-src 'self'; connect-src 'self' wss: https:; media-src 'self' blob:;";
}
生产环境还应当为WebTorrent配置双栈协议。如果用户处于IPv6网络，IPv4的Tracker响应可能会延迟，所以最好同时提供IPv4和IPv6双栈的Tracker地址。国内部署时还要注意WebSocket协议可能被一些公共网络封锁，此时可以尝试从WebRTC降级到HTTP-FLV，利用现有的CDN作为fallback，保证极端情况下的可用性。这种冗余设计也是去中心化平台的精神所在。
通过上述步骤，一个具备PeerTube核心能力的Vue3工程已经初具雏形。从项目结构到P2P传输再到生产部署，每一步都围绕可维护性和扩展性展开。工程化的最终目标是让开发团队在迭代中保持信心，面对联邦宇宙快速增长的数据流时，能够快速定位问题、平滑升级，让去中心化视频分享真正落地。