VidBee Web 全栈实践基于 TanStack Start 的下载客户端开发、构建与部署指南【免费下载链接】VidBeeDownload video and audio from YouTube , TikTok , Twitter , Instagram , Facebook , Twitch , Bilibili , and 1000 sites—or import local media. Create searchable transcripts on your computer, then summarize, translate, or ask questions with your preferred AI provider.项目地址: https://gitcode.com/GitHub_Trending/vi/VidBee本篇技术指南围绕 apps/web/README.md 展开系统讲解 VidBee 开源项目中 Web 端——一个基于 TanStack Start 构建的全栈 React 客户端——的开发启动、构建打包与生产部署全流程。读完本文你将掌握start:web与pnpm --filter ./apps/web两类命令的正确用法、Web 端与 API 服务的联调代理机制、SSR 服务器与 Docker 化的部署方式以及下载设置、RPC 调用等前端核心架构。VidBee Web 是什么VidBee 是一个支持从 YouTube、TikTok、Twitter、Instagram、Facebook、Twitch、Bilibili 等 1000 站点下载音视频并可在本地生成可检索字幕、再交给 AI 总结翻译的多端项目包含桌面端Electron、CLI、浏览器扩展与 Web 端。其中 apps/web 是官方 README 明确定位的TanStack Start client for the VidBee API即 Web 端是一个专门面向 VidBee API 的 TanStack Start 客户端。与桌面端apps/desktop不同Web 端采用前后端分离中的前端自治模式纯 Web 技术栈React 19 TanStack Start全栈框架 Vite 8不依赖 Electron 运行时RPC 直连通过 orpc-client.ts 与 API 服务apps/apiFastify better-sqlite3通信可容器化提供了独立的 Dockerfile 与 docker-compose.yml 编排适合自托管self-host。Web 端与桌面端共享packages/下的核心业务包vidbee/downloader-core、vidbee/subscriptions-core、vidbee/i18n、vidbee/ui等这一点可以从 apps/web/package.json 的workspace:*依赖中直接看到。开发环境与启动命令整个仓库使用 pnpm workspace 管理根目录 package.json 声明packageManager: pnpm11.1.2Web 端开发无需单独安装 Node 依赖——在仓库根目录执行一次pnpm install即可。一键启动pnpm run start:web原文档明确指出start:webis a root workspace script that starts bothapps/webandapps/api.这是最推荐的开发方式根脚本定义如下见 package.jsonstart:web: pnpm -r --parallel --filter ./apps/api --filter ./apps/web run dev它的含义是-r --parallel递归并行执行两个应用同时启动--filter ./apps/api --filter ./apps/web只限定这两个应用各自触发自身的dev脚本见下文。因此一条命令即可同时拉起 API 服务与 Web 前端省去手动管理两个进程的负担。分开启动dev:web与dev:api如果只想单独调试前端也可以拆开执行根脚本pnpm run dev:web # 等价于 pnpm --filter ./apps/web run dev pnpm run dev:api # 等价于 pnpm --filter ./apps/api run devapps/web的dev脚本为vite dev --port 3000见 apps/web/package.json即 Web 开发服务器默认监听3000 端口apps/api的dev脚本为node scripts/ensure-node-sqlite.mjs tsx watch src/index.ts见 apps/api/package.json即 API 服务默认监听3100 端口。开发联调Vite 代理配置Web 端之所以能在开发期独立运行关键在于 vite.config.ts 中的代理配置。开发服务器将四类内部路径转发到 API 服务默认http://localhost:3100可通过VIDBEE_API_URL_INTERNAL环境变量覆盖代理前缀用途/eventsSSE 事件流下载进度、任务状态推送/files已下载文件的访问与下载/rpcorpc RPC 调用下载器、订阅等契约接口/images远程图片代理技术栈与目录结构从 apps/web/package.json 可以看到 Web 端的完整技术选型类别依赖说明全栈框架tanstack/react-startTanStack Start提供 SSR/SSG 与文件路由路由tanstack/react-router类型安全的文件式路由配合tanstack/router-plugin自动生成路由树构建vitevitejs/plugin-reactVite 8 驱动开发与构建样式tailwindcsstailwindcss/vitetw-animate-cssTailwind CSS v4RPCorpc/client、orpc/contract与 API 契约contract类型安全的远程调用国际化i18next、react-i18next、vidbee/i18n多语言支持业务包vidbee/downloader-core等workspace:*包与桌面端共享下载、订阅核心逻辑UIvidbee/ui、lucide-react、sonner共享组件库与通知提示质量biomejs/biome格式化与 Lintsrc/下按职责组织见 apps/web/srcroutes/文件路由定义index.tsx下载页、settings.tsx设置页、subscriptions.tsx订阅页、about.tsx关于页由tanstack/router-plugin在构建时生成 routeTree.gen.tscomponents/pages/与路由一一对应的页面组件download-page.tsx、settings-page.tsx 等components/download/、components/settings/下载对话框、播放列表组、Cookie 设置等业务组件lib/orpc-client.tsRPC 客户端、web-settings.ts浏览器端设置持久化、download-format-preferences.ts格式偏好、i18n.ts等hooks/use-web-download-settings.ts、use-web-settings.ts等 React Hooksstyles.css全局样式入口。路由与页面骨架路由入口 router.tsx 创建 TanStack Router 实例开启了scrollRestoration滚动恢复与defaultPreload: intent按意图预加载。根路由 routes/__root.tsx 负责注入VidBee Web标题与styles.css?url样式表挂载RemoteImageProvider远程图片代理、ShapeProviderUI 圆角上下文客户端水合后读取 Web 设置并应用主题与语言applyThemeToDocumenti18n.changeLanguage集成 TanStack Devtools 与 sonner 通知。各业务路由非常薄只做页面装配例如 routes/index.tsx 将/路由到DownloadPageroutes/settings.tsx 还通过validateSearch解析?tab查询参数用于设置页标签定位。Web 端核心架构解析RPC 客户端与 API 的类型安全通信Web 端不直接写 HTTP 请求而是通过 orpc 客户端调用 API。核心实现在 orpc-client.tsapiUrl解析顺序VITE_API_URL构建期环境变量→ 服务端渲染时取VIDBEE_API_URL_INTERNAL→ 浏览器端取window.location.origin→ 兜底http://api:3100Compose 内部服务名orpcClient基于downloaderContract来自vidbee/downloader-core的契约客户端通过RPCLink指向${apiUrl}/rpcsubscriptionsClient基于subscriptionContract来自vidbee/subscriptions-core/contract指向${apiUrl}/rpc/subscriptions另有eventsUrl/eventsSSE 事件流与fileDownloadUrl/files?path...文件下载两个辅助地址。Web 设置浏览器端持久化web-settings.ts 定义了完整的WebAppSettings接口与默认值通过localStorage的vidbee.web.settings键持久化包含下载路径、最大并发下载数默认 5、Cookie 来源浏览器、代理、语言、主题、一键下载质量best/good/normal/bad/worst、容器格式auto/mp4/mkv/webm/original、字幕语言、文件名风格、ASR 转录档位minimal到quality共 10 档见ASR_TIERS等。所有字段在读取时都经过类型校验与回退处理防止旧版本或脏数据破坏运行时行为。构建打包原文档给出的构建命令为pnpm --filter ./apps/web run build它执行 apps/web/package.json 中的vite build也可以使用等价的根脚本pnpm run build:web。构建产物输出到apps/web/dist/分为dist/client/浏览器端静态资源JS/CSS/图标等dist/server/server.jsSSR 服务器入口TanStack Start 渲染处理器。vite.config.ts 中的关键构建行为define.__APP_VERSION__注入package.json的version字段optimizeDeps.include预构建 React SSR 相关依赖生产构建时ssr.noExternal: true将 CJS 依赖统一打包规避 Vite 8 模块运行器对 CJS 的 ESM 化差异配置注释对此有明确说明。构建后还可执行pnpm run check:web根脚本对应biome check做格式与 Lint 校验。生产部署自研 Node 服务器server.mjsWeb 端生产运行不依赖 Vite而是使用仓库自带的 server.mjs。这是一个无框架的 Node HTTP 服务器按优先级处理三类请求API 代理/events、/files、/images、/rpc前缀的请求被转发到内部 API 服务VIDBEE_API_URL_INTERNAL默认http://api:3100转发时剔除connection、keep-alive等逐跳hop-by-hop头并补充x-forwarded-host、x-forwarded-proto静态文件从dist/client/安全地提供静态资源做了路径穿越防护/assets/下资源使用immutable长缓存其余no-cache并按扩展名设置 Content-TypeSSR 渲染其余路径懒加载dist/server/server.js的默认导出通过 Fetch API 调用 TanStack Start 的渲染处理器完成服务端渲染后流式写回。服务器启动参数通过环境变量控制server.mjsVIDBEE_WEB_HOST监听地址默认0.0.0.0VIDBEE_WEB_PORT监听端口默认3000必须是 165535 的整数否则启动即报错。Docker 化部署Web 端提供了两阶段构建的 Dockerfile基于node:22-alpinebuilder 阶段开启 corepack使用pnpm install --filter {./apps/web}... --frozen-lockfile --ignore-scripts只安装 Web 及其 workspace 依赖随后pnpm --filter ./apps/web run build产出dist/runner 阶段仅拷贝dist/、server.mjs与必要的vidbee/logger运行时以非 root 用户node运行EXPOSE 3000CMD [node, server.mjs]。与 API 一起编排docker-compose根目录 docker-compose.yml 定义了api与web两个服务web服务构建自apps/web/Dockerfile通过VIDBEE_API_URL_INTERNAL: http://api:${VIDBEE_API_PORT:-3100}指向 Compose 网络内的 API 服务并depends_onAPI 的健康检查/health对外暴露${VIDBEE_WEB_PORT:-3000}:3000VIDBEE_ALLOWED_HOSTS自托管者若使用反向代理如 Traefik需将域名加入 Vite 的 host 检查白名单设为*或all表示放开逗号分隔列表可指定多个域名详见 vite.config.ts 注释对应 GitHub issue #404 场景VIDBEE_DOWNLOAD_DIR_HOST支持将下载目录绑定挂载到 NAS 等宿主机路径。环境变量速查变量生效阶段默认值作用VIDBEE_API_URL_INTERNAL开发/生产http://localhost:3100开发、http://api:3100容器API 服务地址用于代理与 SSR 期 RPCVITE_API_URL构建期无覆盖浏览器端 API 地址去除尾部斜杠后使用VIDBEE_ALLOWED_HOSTS开发/生产无Vite/服务器允许的 Host 白名单*或all放开VIDBEE_WEB_HOST生产0.0.0.0Web 服务器监听地址VIDBEE_WEB_PORT生产3000Web 服务器监听端口165535PORTLESS_URL/PORT开发无强制开发服务器绑定127.0.0.1与指定端口strictPort结语从 apps/web/README.md 的两条命令出发本文还原了 VidBee Web 从开发启动pnpm run start:web并行拉起 Web 与 API、类型安全 RPC 通信、浏览器端设置持久化到pnpm --filter ./apps/web run build构建、server.mjsSSR 托管与 Docker Compose 自托管部署的完整链路。Web 端借助 TanStack Start 与 orpc 契约把桌面端沉淀的下载、订阅、转录能力以轻量全栈 Web 形态开放出来。若需继续深入可阅读 orpc-client.ts、web-settings.ts、server.mjs 与 docker-compose.yml 的完整实现。【免费下载链接】VidBeeDownload video and audio from YouTube , TikTok , Twitter , Instagram , Facebook , Twitch , Bilibili , and 1000 sites—or import local media. Create searchable transcripts on your computer, then summarize, translate, or ask questions with your preferred AI provider.项目地址: https://gitcode.com/GitHub_Trending/vi/VidBee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
VidBee Web 全栈实践：基于 TanStack Start 的下载客户端开发、构建与部署指南
VidBee Web 全栈实践基于 TanStack Start 的下载客户端开发、构建与部署指南【免费下载链接】VidBeeDownload video and audio from YouTube , TikTok , Twitter , Instagram , Facebook , Twitch , Bilibili , and 1000 sites—or import local media. Create searchable transcripts on your computer, then summarize, translate, or ask questions with your preferred AI provider.项目地址: https://gitcode.com/GitHub_Trending/vi/VidBee本篇技术指南围绕 apps/web/README.md 展开系统讲解 VidBee 开源项目中 Web 端——一个基于 TanStack Start 构建的全栈 React 客户端——的开发启动、构建打包与生产部署全流程。读完本文你将掌握start:web与pnpm --filter ./apps/web两类命令的正确用法、Web 端与 API 服务的联调代理机制、SSR 服务器与 Docker 化的部署方式以及下载设置、RPC 调用等前端核心架构。VidBee Web 是什么VidBee 是一个支持从 YouTube、TikTok、Twitter、Instagram、Facebook、Twitch、Bilibili 等 1000 站点下载音视频并可在本地生成可检索字幕、再交给 AI 总结翻译的多端项目包含桌面端Electron、CLI、浏览器扩展与 Web 端。其中 apps/web 是官方 README 明确定位的TanStack Start client for the VidBee API即 Web 端是一个专门面向 VidBee API 的 TanStack Start 客户端。与桌面端apps/desktop不同Web 端采用前后端分离中的前端自治模式纯 Web 技术栈React 19 TanStack Start全栈框架 Vite 8不依赖 Electron 运行时RPC 直连通过 orpc-client.ts 与 API 服务apps/apiFastify better-sqlite3通信可容器化提供了独立的 Dockerfile 与 docker-compose.yml 编排适合自托管self-host。Web 端与桌面端共享packages/下的核心业务包vidbee/downloader-core、vidbee/subscriptions-core、vidbee/i18n、vidbee/ui等这一点可以从 apps/web/package.json 的workspace:*依赖中直接看到。开发环境与启动命令整个仓库使用 pnpm workspace 管理根目录 package.json 声明packageManager: pnpm11.1.2Web 端开发无需单独安装 Node 依赖——在仓库根目录执行一次pnpm install即可。一键启动pnpm run start:web原文档明确指出start:webis a root workspace script that starts bothapps/webandapps/api.这是最推荐的开发方式根脚本定义如下见 package.jsonstart:web: pnpm -r --parallel --filter ./apps/api --filter ./apps/web run dev它的含义是-r --parallel递归并行执行两个应用同时启动--filter ./apps/api --filter ./apps/web只限定这两个应用各自触发自身的dev脚本见下文。因此一条命令即可同时拉起 API 服务与 Web 前端省去手动管理两个进程的负担。分开启动dev:web与dev:api如果只想单独调试前端也可以拆开执行根脚本pnpm run dev:web # 等价于 pnpm --filter ./apps/web run dev pnpm run dev:api # 等价于 pnpm --filter ./apps/api run devapps/web的dev脚本为vite dev --port 3000见 apps/web/package.json即 Web 开发服务器默认监听3000 端口apps/api的dev脚本为node scripts/ensure-node-sqlite.mjs tsx watch src/index.ts见 apps/api/package.json即 API 服务默认监听3100 端口。开发联调Vite 代理配置Web 端之所以能在开发期独立运行关键在于 vite.config.ts 中的代理配置。开发服务器将四类内部路径转发到 API 服务默认http://localhost:3100可通过VIDBEE_API_URL_INTERNAL环境变量覆盖代理前缀用途/eventsSSE 事件流下载进度、任务状态推送/files已下载文件的访问与下载/rpcorpc RPC 调用下载器、订阅等契约接口/images远程图片代理技术栈与目录结构从 apps/web/package.json 可以看到 Web 端的完整技术选型类别依赖说明全栈框架tanstack/react-startTanStack Start提供 SSR/SSG 与文件路由路由tanstack/react-router类型安全的文件式路由配合tanstack/router-plugin自动生成路由树构建vitevitejs/plugin-reactVite 8 驱动开发与构建样式tailwindcsstailwindcss/vitetw-animate-cssTailwind CSS v4RPCorpc/client、orpc/contract与 API 契约contract类型安全的远程调用国际化i18next、react-i18next、vidbee/i18n多语言支持业务包vidbee/downloader-core等workspace:*包与桌面端共享下载、订阅核心逻辑UIvidbee/ui、lucide-react、sonner共享组件库与通知提示质量biomejs/biome格式化与 Lintsrc/下按职责组织见 apps/web/srcroutes/文件路由定义index.tsx下载页、settings.tsx设置页、subscriptions.tsx订阅页、about.tsx关于页由tanstack/router-plugin在构建时生成 routeTree.gen.tscomponents/pages/与路由一一对应的页面组件download-page.tsx、settings-page.tsx 等components/download/、components/settings/下载对话框、播放列表组、Cookie 设置等业务组件lib/orpc-client.tsRPC 客户端、web-settings.ts浏览器端设置持久化、download-format-preferences.ts格式偏好、i18n.ts等hooks/use-web-download-settings.ts、use-web-settings.ts等 React Hooksstyles.css全局样式入口。路由与页面骨架路由入口 router.tsx 创建 TanStack Router 实例开启了scrollRestoration滚动恢复与defaultPreload: intent按意图预加载。根路由 routes/__root.tsx 负责注入VidBee Web标题与styles.css?url样式表挂载RemoteImageProvider远程图片代理、ShapeProviderUI 圆角上下文客户端水合后读取 Web 设置并应用主题与语言applyThemeToDocumenti18n.changeLanguage集成 TanStack Devtools 与 sonner 通知。各业务路由非常薄只做页面装配例如 routes/index.tsx 将/路由到DownloadPageroutes/settings.tsx 还通过validateSearch解析?tab查询参数用于设置页标签定位。Web 端核心架构解析RPC 客户端与 API 的类型安全通信Web 端不直接写 HTTP 请求而是通过 orpc 客户端调用 API。核心实现在 orpc-client.tsapiUrl解析顺序VITE_API_URL构建期环境变量→ 服务端渲染时取VIDBEE_API_URL_INTERNAL→ 浏览器端取window.location.origin→ 兜底http://api:3100Compose 内部服务名orpcClient基于downloaderContract来自vidbee/downloader-core的契约客户端通过RPCLink指向${apiUrl}/rpcsubscriptionsClient基于subscriptionContract来自vidbee/subscriptions-core/contract指向${apiUrl}/rpc/subscriptions另有eventsUrl/eventsSSE 事件流与fileDownloadUrl/files?path...文件下载两个辅助地址。Web 设置浏览器端持久化web-settings.ts 定义了完整的WebAppSettings接口与默认值通过localStorage的vidbee.web.settings键持久化包含下载路径、最大并发下载数默认 5、Cookie 来源浏览器、代理、语言、主题、一键下载质量best/good/normal/bad/worst、容器格式auto/mp4/mkv/webm/original、字幕语言、文件名风格、ASR 转录档位minimal到quality共 10 档见ASR_TIERS等。所有字段在读取时都经过类型校验与回退处理防止旧版本或脏数据破坏运行时行为。构建打包原文档给出的构建命令为pnpm --filter ./apps/web run build它执行 apps/web/package.json 中的vite build也可以使用等价的根脚本pnpm run build:web。构建产物输出到apps/web/dist/分为dist/client/浏览器端静态资源JS/CSS/图标等dist/server/server.jsSSR 服务器入口TanStack Start 渲染处理器。vite.config.ts 中的关键构建行为define.__APP_VERSION__注入package.json的version字段optimizeDeps.include预构建 React SSR 相关依赖生产构建时ssr.noExternal: true将 CJS 依赖统一打包规避 Vite 8 模块运行器对 CJS 的 ESM 化差异配置注释对此有明确说明。构建后还可执行pnpm run check:web根脚本对应biome check做格式与 Lint 校验。生产部署自研 Node 服务器server.mjsWeb 端生产运行不依赖 Vite而是使用仓库自带的 server.mjs。这是一个无框架的 Node HTTP 服务器按优先级处理三类请求API 代理/events、/files、/images、/rpc前缀的请求被转发到内部 API 服务VIDBEE_API_URL_INTERNAL默认http://api:3100转发时剔除connection、keep-alive等逐跳hop-by-hop头并补充x-forwarded-host、x-forwarded-proto静态文件从dist/client/安全地提供静态资源做了路径穿越防护/assets/下资源使用immutable长缓存其余no-cache并按扩展名设置 Content-TypeSSR 渲染其余路径懒加载dist/server/server.js的默认导出通过 Fetch API 调用 TanStack Start 的渲染处理器完成服务端渲染后流式写回。服务器启动参数通过环境变量控制server.mjsVIDBEE_WEB_HOST监听地址默认0.0.0.0VIDBEE_WEB_PORT监听端口默认3000必须是 165535 的整数否则启动即报错。Docker 化部署Web 端提供了两阶段构建的 Dockerfile基于node:22-alpinebuilder 阶段开启 corepack使用pnpm install --filter {./apps/web}... --frozen-lockfile --ignore-scripts只安装 Web 及其 workspace 依赖随后pnpm --filter ./apps/web run build产出dist/runner 阶段仅拷贝dist/、server.mjs与必要的vidbee/logger运行时以非 root 用户node运行EXPOSE 3000CMD [node, server.mjs]。与 API 一起编排docker-compose根目录 docker-compose.yml 定义了api与web两个服务web服务构建自apps/web/Dockerfile通过VIDBEE_API_URL_INTERNAL: http://api:${VIDBEE_API_PORT:-3100}指向 Compose 网络内的 API 服务并depends_onAPI 的健康检查/health对外暴露${VIDBEE_WEB_PORT:-3000}:3000VIDBEE_ALLOWED_HOSTS自托管者若使用反向代理如 Traefik需将域名加入 Vite 的 host 检查白名单设为*或all表示放开逗号分隔列表可指定多个域名详见 vite.config.ts 注释对应 GitHub issue #404 场景VIDBEE_DOWNLOAD_DIR_HOST支持将下载目录绑定挂载到 NAS 等宿主机路径。环境变量速查变量生效阶段默认值作用VIDBEE_API_URL_INTERNAL开发/生产http://localhost:3100开发、http://api:3100容器API 服务地址用于代理与 SSR 期 RPCVITE_API_URL构建期无覆盖浏览器端 API 地址去除尾部斜杠后使用VIDBEE_ALLOWED_HOSTS开发/生产无Vite/服务器允许的 Host 白名单*或all放开VIDBEE_WEB_HOST生产0.0.0.0Web 服务器监听地址VIDBEE_WEB_PORT生产3000Web 服务器监听端口165535PORTLESS_URL/PORT开发无强制开发服务器绑定127.0.0.1与指定端口strictPort结语从 apps/web/README.md 的两条命令出发本文还原了 VidBee Web 从开发启动pnpm run start:web并行拉起 Web 与 API、类型安全 RPC 通信、浏览器端设置持久化到pnpm --filter ./apps/web run build构建、server.mjsSSR 托管与 Docker Compose 自托管部署的完整链路。Web 端借助 TanStack Start 与 orpc 契约把桌面端沉淀的下载、订阅、转录能力以轻量全栈 Web 形态开放出来。若需继续深入可阅读 orpc-client.ts、web-settings.ts、server.mjs 与 docker-compose.yml 的完整实现。【免费下载链接】VidBeeDownload video and audio from YouTube , TikTok , Twitter , Instagram , Facebook , Twitch , Bilibili , and 1000 sites—or import local media. Create searchable transcripts on your computer, then summarize, translate, or ask questions with your preferred AI provider.项目地址: https://gitcode.com/GitHub_Trending/vi/VidBee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
