简介：一套以隐私保护与自主访问为核心理念的YouTube前端替代方案，基于Invidious构建，既可直接部署用于浏览和观看YouTube视频，也适合开发者进行二次定制。压缩包体积约3.32MB，共347个文件，以Crystal源码（cr）、Ecr模板和JSON配置为主体，同时包含JS/CSS静态资源、图标字体、shell脚本以及Dockerfile、YAML等部署文件，类型覆盖前端渲染、后端逻辑与容器化运行等多个环节，整体结构紧凑且模块边界清晰。源码按代理、视频解析、API交互、播放列表等功能模块划分，配合多平台构建配置，可帮助读者快速拆解Invidious的视频解析与数据组织方式，进而搭建属于自己的个性化视频前端。已有8532人学习下载，适合关注隐私保护、希望摆脱官方界面限制，同时具备一定动手能力或学习意愿的用户参考实践。

1. 用前端镜像替代 YouTube：一个独立前端能解决什么

周五晚上你只想把某个频道还没看完的系列追完，结果官方页面光页头就推了一屏“你可能感兴趣”，播放器弹窗挡两下，广告缓冲转半天，真正的视频反而被挤到最下面。这个镜像版做的就是把 UI 层整个换掉——不动上游数据，只做一个前端渲染层的替代品，让你打开页面直接看到搜索结果、播放器和视频描述，页面干净、加载也轻得多。它本质上是给“浏览+播放”这个诉求换了一套更纯粹的界面，适合三类人：被官方界面搞到厌烦的普通用户、想拿现成项目做前端开发实战练手的学习者，以及要在内网搭一套“只看不评”的视频展示页的团队。这类项目最常见的形态是一个独立前端工程加一个轻量代理层，前后端加起来也就几百行核心代码，部署成本很低。

2. 镜像前端不是黑匣子：数据来源与前端选型逻辑

很多第一次接触这类项目的人，会误以为“镜像”就是把整个网站文件下载下来再传到自己服务器上跑。实际拆过之后你会发现，真正能长期维护的镜像前端，几乎都不会去存整站数据，而是做“请求转发 + 前端重排”。

2.1 镜像前端的两种形态：静态快照和动态代理

静态快照的做法是定期抓取目标页面的 HTML，把页面结构原样保存，访问镜像站时直接吐给浏览器。优点是实现简单，缺点是一周之后就全是死链，视频地址过期、评论加载不出来，维护成本很高。动态代理的做法完全不同：前端页面上根本没有真实数据，所有搜索、列表、视频信息都是浏览器端发请求给一个中转服务，中转服务再去上游拉数据，拿到之后交给前端重新渲染。这个镜像版项目走的就是第二种，所以它不碰上游的账号体系和评论系统，只做公开内容的浏览与播放。

数据链路大致是：浏览器里的前端 → 镜像代理服务 → 上游接口 → 返回 JSON → 前端组件渲染。前端组件库在这里承担了几乎所有界面工作，列表、详情、播放器都是独立组件，上游返回什么结构，前端就按什么结构渲染。这意味着只要上游接口的返回格式稳定，你可以随时调整 UI，不影响数据获取。我从这个项目里学到的第一课就是：所谓“替代产品”，真正替换的只是表现层，数据层永远是别人的，别想着全盘复制。

2.2 前端技术栈选型：为什么用轻量 SPA 而不是重框架

做这类镜像前端，最常被问的问题是用 Vue 还是 React，需不需要上 SSR。常见做法是选一个轻量 SPA 框架，配一个极简的组件库，播放器单独接。原因很直接：这个场景没有 SEO 需求，用户打开页面就是要看视频、搜东西，首屏越快越好，交互越直接越好，SSR 在这里属于过度设计。我自己一般选 Vue 3 + Vite，组件用项目内置的轻量组件，不额外引大型 UI 框架，因为核心界面就搜索框、列表卡片、播放器三个模块，引一套重型组件库反而是负担。

播放器这一层是重点。上游流媒体地址多数时候不是直接给你一个 mp4，而是带签名参数的视频流地址，播放器常见接入方式是 hls.js 或同类库转成可播片段，再交给 video 标签。参数层面，你需要关心的主要是清晰度切换、自动播放和进度恢复三个点。清晰度切换要拿到不同码率的流地址列表，自动播放要处理浏览器策略——带声音自动播放通常被拦，进度恢复则要靠本地存储记录播放时间。

2.3 代理层：为什么前端不能直接连上游

新手最容易翻车的地方在这里：前端代码写好了，一请求上游接口就报跨域。浏览器的同源策略决定了前端不能随便跨域拉数据，这个镜像项目因此必须有一个服务端代理做中转。代理层做的事很简单——接收前端的请求，带上必要的请求头去上游取数据，再把 JSON 原样返回给前端。别小看这一层，它同时解决了三件事：跨域、请求头伪装、以及把上游接口的变动收敛到一个地方。

我一般会建议代理层独立成一个几十行的 Node 服务，不走前端工程自身的 dev server，这样本地开发和线上部署都能用一个入口。实现上就是 req 进来，改写 URL 和 headers，用 http 模块转发，res 回传。核心代码不超过 50 行，但它是整个镜像前端能不能跑通的关键，后面的部署章节我会专门讲它的配置。

3. 从拉代码到跑起来：部署这套前端镜像的完整命令链

这一章直接进入实操。如果你拿到的是源码包，目录结构一般是frontend/（Vue 或 React 工程）和server/（代理服务）两个部分，如果没有严格区分，也一定会有两个入口文件。下面按标准流程走一遍。

3.1 拉取代码与初始化依赖

git clone <项目地址> youtube-mirror cd youtube-mirror npm install

逻辑说明：先拉取项目到本地，进入根目录后安装依赖。如果项目里同时有package.json和server/package.json，说明前后端依赖分离，需要分别安装。

参数说明：推荐 Node 18 及以上版本，Vite 工程对 Node 版本有硬性要求，太老的版本会直接报错。npm install装完如果出现ERESOLVE错误，多数是依赖树冲突，可以加--legacy-peer-deps重试，这是前端工程里最常见的老问题之一。

3.2 改配置：端口、上游地址与路径前缀

大部分镜像前端都会把配置收敛到一个.env或config.js文件里，你需要改的核心配置项往往只有三到五个。下面这份表格是我从项目里拆出来的典型配置。

这里的VITE_BASE_PATH是最阴间的配置。如果你把前端部署在服务器根路径，保持/不用动；如果要部署到https://域名/mirror/这样的子目录，必须改成/mirror/，否则构建出来的 JS/CSS 引用路径全是/assets/...，放到子目录下全部 404，页面白屏且控制台只报资源加载失败。这种问题排查半天发现是少配一个路径前缀，非常浪费人生。

3.3 本地联调：把前端和代理服务同时跑起来

# 终端一：启动代理服务 node server/index.js # 终端二：启动前端开发服务器 npm run dev

逻辑说明：代理服务先监听 3000 端口，前端开发服务器起来之后，浏览器访问的是前端地址，前端所有/api/...请求被 Vite 的 dev server 代理到http://localhost:3000，这样本地就没有跨域问题。

参数说明：Vite 的代理配置在vite.config.js里，写法是server.proxy里把/api指向http://localhost:3000。如果你的实际项目里没有这一段，要手动补上，否则本地联调时前端请求会直接打到前端自身的 dev server，得到一个类 HTML 的错误页面，而不是 JSON。

3.4 生产部署：构建静态文件并配置反向代理

npm run build

逻辑说明：构建产物会输出到dist/目录，把这个目录上传到服务器，再用 Nginx 托管。同时 Nginx 需要把/api路径的请求转发到代理服务的端口，这一步非常关键——前端的 JS 是在用户浏览器里跑的，它本身没有跨域问题，因为访问的是同域路径，但 Nginx 要负责把这些请求转到真正的代理服务。

server { listen 80; server_name your-domain.com; root /var/www/youtube-mirror/dist; index index.html; location /api/ { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location / { try_files $uri $uri/ /index.html; } }

逻辑说明：location /api/块把所有前端代理请求转发给本地 3000 端口的 Node 服务，try_files这行是 SPA 路由的关键——前端路由用的是 history 模式，刷新/watch?id=xxx这个路径时，Nginx 找不到对应的物理文件，必须回退到index.html让前端重新接管路由。没有这行，页面一刷新就是 404，这属于部署阶段的头号翻车点。

4. 避坑指南：镜像前端五个高频翻车点

这一章是我拆这类项目时踩出来的血泪记录，全按“现象 → 原因 → 解决”的格式写，希望能帮你省掉几个晚上的排查时间。

4.1 播放器区域全黑，控制台报跨域错误

• 现象：列表页、详情页都正常，点开视频后播放器区域全黑，控制台出现CORS policy相关报错。
• 原因：前端直连了上游的流媒体地址或缩略图地址，浏览器拦截了跨域响应。代理层只转了接口请求，没有处理媒体文件请求。
• 解决：把所有媒体相关请求也打进代理层，在代理服务里做一层路径映射，比如/proxy?url=<视频地址>这样的通用转发接口。或者更省事，让代理服务修改响应头，加上Access-Control-Allow-Origin: *。注意，修改响应头只能解决没有签名限制的视频地址，签名类地址要由代理转发才行。

4.2 视频播放到一半突然中断，重新加载又能看

• 现象：点开视频能播放，但播到某个时间点突然断流，刷新后又从开头播放，拖进度条到中断点依旧断。
• 原因：视频流地址携带签名参数，签名有有效期，代理层拿到的地址是几十秒前生成的，等到真正播到后面的分段时签名失效。
• 解决：在播放器初始化之后，监听播放中断事件，一旦断流，立即重新请求一次上游地址拿到新签名，替换播放源。这里要给播放器接入一个断流重试机制，常见做法是video标签的error事件触发时重新拉流，代码大致是：

videoElement.addEventListener('error', () => { fetch(`/api/video-url?id=${videoId}`) .then((res) => res.json()) .then((data) => { videoElement.src = data.url videoElement.play() }) })

逻辑说明：重新请求接口会拿到一个新的签名地址，替换src后继续播放。注意找到断流前的播放时间点，用currentTime续播，避免从头再来。参数说明：videoId是当前视频的 ID，video-url接口是代理层预设的取流接口，你拿到源码包后可以在server/目录里搜到对应路由。

4.3 搜索结果偶尔为空，接口返回的字段变了

• 现象：大多数关键词检索正常，某些特殊字符或者热门关键词搜索后列表为空，对比接口数据发现字段名不完全匹配。
• 原因：上游接口的返回结构发生过调整，字段title改成了name，或者列表从数组变成了嵌套结构，前端的解析逻辑没跟上。
• 解决：不要在前端业务代码里到处直接取字段，把数据解析收敛到一个独立模块里，解析函数做默认值兜底。字段变化时只改一个文件，而不是全局搜替换。这属于“数据解析层要单独封装”的典型教训，解析层做得好，上游接口变动对你就是改一行配置的事。

4.4 列表页图片一片空白，滚动后偶尔出现

• 现象：视频列表能加载，但缩略图全是灰色块，慢慢滚动页面后图片逐渐出现。
• 原因：上游缩略图地址在静态资源引用时没走代理，浏览器拦截跨域；或者前端用了懒加载，但懒加载组件的触发判断有误，没把滚动容器识别对。
• 解决：两步走。先看图片地址是不是相对路径——如果是//开头的协议相对地址，要补全为https:；如果不是，就把图片地址也从代理层走一遍。懒加载的问题，检查滚动容器绑定的是window还是某个div，如果页面最外层容器发生了滚动，而懒加载监听的是内部容器，就会出现“滑下去不触发加载”的玄学现象。

4.5 部署子目录后全站白屏，接口请求全部 404

• 现象：放在服务器根路径跑得好好的，移到https://域名/mirror/之后，打开首页白屏，控制台一堆 404。
• 原因：前端工程里静态资源引用的绝对路径写死了，没有跟随部署子路径变化。构建时会生成/assets/index.js这样的引用，它在子目录下找域名/assets/...而不是域名/mirror/assets/...。
• 解决：这个坑我在 3.2 节提醒过，构建前先检查VITE_BASE_PATH或 Vite 的base配置。另外接口代理请求前缀也要对应调整，如果代理配置写的是/api，但实际部署在/mirror/下，要么让 Nginx 把/mirror/api转移到代理服务，要么前端请求路径写/mirror/api。我自己的习惯是：前端请求路径永远写相对路径或者基于import.meta.env.BASE_URL拼接，保证换部署位置不用改代码。

5. 进阶改造：给镜像前端加频道订阅与播放进度恢复

基础功能跑通之后，下一步就是做体验优化。很多镜像前端是不带“订阅”概念的，因为不碰账号体系，但你可以用localStorage做一套纯本地的订阅关系，不需要后端存任何数据。这块改造涉及两个核心方法：保存订阅列表和读取播放进度。

// 频道订阅：存的是频道 ID 列表 function toggleSubscribe(channelId, channelName) { const key = `sub_${channelId}` if (localStorage.getItem(key)) { localStorage.removeItem(key) } else { localStorage.setItem(key, JSON.stringify({ name: channelName, time: Date.now() })) } } // 播放进度：保存视频 ID 对应的播放位置 function saveProgress(videoId, currentTime) { localStorage.setItem( `progress_${videoId}`, JSON.stringify({ time: currentTime, updatedAt: Date.now() }) ) } function getProgress(videoId) { const raw = localStorage.getItem(`progress_${videoId}`) if (!raw) return 0 return JSON.parse(raw).time }

逻辑说明：订阅用频道 ID 作为 key，切换时写入或删除，读取时遍历localStorage里所有以sub_开头的 key。播放进度以视频 ID 为 key，播放器timeupdate事件里每几秒调一次saveProgress，再次打开播放器时初始化currentTime。

参数说明：saveProgress建议做节流，不要每 100ms 写一次localStorage。我习惯用 3 秒写一次的频率，配合页面卸载前主动保存一次，基本能做到断点续播无感。播放器初始化时恢复进度的代码放loadedmetadata事件里，因为此时视频源已就绪，才能设置currentTime。

验证这套改造的办法很简单：播放一个视频到 1 分钟处关掉页面，重新打开该视频确认是否从 1 分钟附近续播；订阅一个频道，清空浏览器缓存后再打开页面确认订阅列表是否还在。这两项都通过，你的本地持久化就立住了。

这里提醒一句：localStorage的读写是同步的，数据量很小，没问题；但不要把视频播放列表也整个塞进去，容量一超就全清空。从那以后，我每次给这类镜像前端加本地功能，都强制走一遍“数据量评估 → 缓存策略 → 失效兜底”，避免把浏览器存储当后端数据库用。希望帮到你。

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