galaxy-downloader 是一款支持 Bilibili、抖音、小红书、TikTok 等平台视频与音频下载的通用媒体下载工具。本文带你完整解析它的技术架构：基于 Next.js 16 App Router 与 React 19 构建前端，用 Vite 8 生态的 vinext 完成构建，最终一键部署到 Cloudflare Workers——没有传统 Node 服务器，纯边缘运行的现代全栈方案。

一、技术栈总览：一张表看懂选型

项目所有版本信息集中在 package.json 中，核心依赖如下：

值得注意的亮点：next.config.ts 中开启了cacheComponents与reactCompiler，并针对lucide-react、Radix UI 等组件库启用了optimizePackageImports自动按需导入，进一步压缩产物体积。

二、目录结构：代码是怎么组织的

仓库采用清晰的 App Router 分层结构：

• src/app/：Next.js 路由层，[locale]动态段承载全部多语言页面，api/proxy-image提供图片代理
• src/components/：UI 组件，按downloader/、audio-tool/、layout/、ui/分组
• src/lib/：核心逻辑，含平台识别、统一解析请求、HLS 下载、FFmpeg 封装
• src/i18n/：next-intl 路由与字典配置
• worker/index.ts：Cloudflare Worker 入口
• scripts/：部署重试、图标与 OG 图生成脚本
• tests/：Vitest 单元测试

三、前端层：Next.js 16 + React 19 的页面架构

首页入口 src/app/[locale]/page.tsx 是一个典型的 RSC 页面：服务端读取对应语言的字典，再组合UnifiedDownloaderClient核心下载器与统计卡片、平台指南等侧栏组件。

国际化路由是架构中的一环。src/proxy.ts 作为 Next.js 中间件，对没有语言前缀的请求解析Accept-Language与 Cookie，用 308 永久重定向到对应语言路径，并写入 Cookie 记住偏好（对爬虫不写入），配合 src/i18n/routing.ts 与 src/lib/i18n/config.ts 定义的 6 种语言（zh、zh-tw、en、ja、es、ru）。

SEO 细节做得相当扎实：布局文件 src/app/[locale]/layout.tsx 中generateMetadata按语言生成 title、Open Graph 与 hreflang 备选链接，generateStaticParams让各语言页面全部静态化，并输出 src/app/sitemap.ts 与 src/app/robots.ts。

四、构建层：Vite 8 + vinext 如何替代 Webpack

这是本项目最有意思的部分。它没有用 Next.js 自带的 webpack 构建，而是通过vinext（Cloudflare 官方 Next.js on Vite 方案）+@cloudflare/vite-plugin完成构建，配置全部在 vite.config.ts：

1. vinext()插件接管 App Router 的编译流程，viteEnvironment将rsc环境设为主环境、ssr作为子环境；
2. cloudflare()插件让构建产物直接适配 Workers 运行时（nodejs_compat兼容模式）；
3. 生产构建时额外挂载Serwist（Workbox 生态）插件，自动从 src/sw.ts 生成 Service Worker，预缓存 JS/CSS 与图标，并把 FFmpeg WASM 文件按"CacheFirst + 一年过期"策略缓存，实现 PWA 离线可用。

开发体验同样受益于 Vite：pnpm dev一条命令先同步 FFmpeg core 资源再启动开发服务器（端口 3010），无需额外配置。

五、部署层：Cloudflare Workers 边缘托管

wrangler.jsonc 定义了部署形态：

• main指向 worker/index.ts，静态产物来自dist/client，通过ASSETS绑定由 Worker 直接返回；
• IMAGES绑定接入 Cloudflare Images，Worker 入口中拦截/_vinext/image路径，用边缘图像管线完成 Next.js 图片优化——图片压缩发生在边缘节点而非自建服务器；
• 开启 observability 日志与 traces，便于排查边缘请求。

部署流程由 scripts/deploy-with-retry.mjs 包装：调用vinext deploy，并只对 Cloudflare API 的971 限流错误做指数退避重试（60/120/180 秒），其他错误立即失败，避免掩盖真实配置问题。pnpm deploy一条命令即可完成"同步 FFmpeg 资源 → 构建 → 重试部署"全流程。

六、浏览器端媒体处理：下载工具的核心能力

解析请求在 src/lib/config.ts 中统一配置——前端直接请求公开 API（/api/parse、/api/download、/api/play），注释中说明了原因：让 Cloudflare 按最终用户 IP 限流，而不是被同一出口 IP 聚合。src/lib/unified-parse.ts 封装了解析流程并带错误分类。

更关键的是，重活几乎都在浏览器本地完成：

• 音频提取：src/lib/ffmpeg.ts 封装 FFmpeg.wasm，优先加载本仓库内置的/ffmpeg-core分片资源，失败时回退到 CDN，提取 MP3 无需服务器算力；
• HLS 下载：src/lib/hls-browser-download.ts 用hls-parser解析 m3u8 播放列表，逐段下载并合并，还处理了 byterange 与加密流边界情况；
• 图文打包：JSZip 在前端把多图压缩成 ZIP 供下载。

这意味着 Worker 端几乎没有计算压力，媒体文件的"重量级"工作全部卸载给了浏览器与 CDN。

七、本地运行与部署指南

克隆仓库后（仓库地址：https://gitcode.com/gh_mirrors/ga/galaxy-downloader）：

pnpm install # 安装依赖 pnpm dev # 启动开发服务器（localhost:3010） pnpm build # 生产构建 pnpm deploy # 构建并发布到 Cloudflare Workers

常用环境变量：NEXT_PUBLIC_API_BASE_URL（解析 API 地址）、NEXT_PUBLIC_SITE_URL（站点基址）、SEO_INDEXABLE（是否允许搜索引擎索引）。

八、总结

galaxy-downloader 的架构可以概括为一句话：Next.js 16 写页面，Vite 8 做构建，Workers 跑运行时，浏览器干重活。它展示了 2026 年前后"无服务器"全栈应用的成熟形态——边缘部署、静态优先、WASM 本地计算，对于想学习现代前端工程化与边缘计算的开发者来说，这是一个非常值得参考的完整样本。