一款基于 WXT 框架开发的现代化 YouTube 视频下载浏览器扩展,支持多种视频质量和音频格式,提供流畅的用户体验。

• 多种清晰度支持: 8K, 4K, 2K, 1080p, 720p, 480p, 360p
• 格式: MP4 (H.264/H.265 编码)
• 实时进度显示: 下载过程中显示实时进度条
• 断点续传: 支持大文件的可靠下载

• MP3: 128kbps 高质量音频
• FLAC: 无损音质
• WAV: 未压缩音频格式

• 明暗主题切换: 自动适配 YouTube 界面主题
• 优雅的面板设计: 可折叠的下载选项面板
• 智能通知系统: 使用 iziToast 提供友好的操作反馈
• Aether 美学: 遵循 rounded-2xl 圆角和流畅动画设计规范
• 安全可靠: 集成 Trusted Types 策略,防止 XSS 攻击

• Node.js >= 18.0.0
• npm 或 pnpm 包管理器
• Chrome/Edge/Firefox 浏览器 (支持 Manifest V3)

1. 克隆仓库

git clone https://github.com/yourusername/youtube-downloader.git
cd youtube-downloader

2. 安装依赖

npm install
# 或使用 pnpm
pnpm install

3. 启动开发模式

# Chrome/Edge 开发
npm run dev

# Firefox 开发
npm run dev:firefox

1. 打开 chrome://extensions/ (或 edge://extensions/)
2. 启用右上角的 "开发者模式"
3. 点击 "加载已解压的扩展程序"
4. 选择项目的 .output/chrome-mv3 目录

1. 打开 about:debugging#/runtime/this-firefox
2. 点击 "临时载入附加组件"
3. 选择项目的 .output/firefox-mv2 目录中的 manifest.json

• 框架: WXT 0.18.0 - 现代化浏览器扩展开发框架
• 语言: TypeScript 5.x
• 通知库: iziToast 1.4.0
• 后端 API: ytd.suck-dick.tech 视频处理服务
• 安全特性: Trusted Types (CSP 兼容)

youtube-downloader/
├── entrypoints/
│   ├── youtube.content.ts    # 主内容脚本
│   └── style.css             # 自定义样式
├── public/
│   └── icon/                 # 扩展图标资源
├── webfonts/                 # Font Awesome 字体文件
├── wxt.config.ts             # WXT 配置文件
├── tsconfig.json             # TypeScript 配置
└── package.json              # 项目依赖

命令	说明
npm run dev	启动 Chrome 开发模式 (热重载)
npm run dev:firefox	启动 Firefox 开发模式
npm run build	构建生产版本 (Chrome/Edge)
npm run build:firefox	构建 Firefox 版本
npm run zip	打包为 .zip 文件用于发布
npm run zip:firefox	打包 Firefox 版本

export default defineContentScript({
  matches: ['*://www.youtube.com/*'],
  main() {
    // 1. 检测 YouTube 页面加载
    // 2. 注入下载按钮到播放器控制栏
    // 3. 创建可折叠的下载选项面板
    // 4. 监听用户交互事件
  }
});

1. 视频信息获取: 解析 YouTube 页面 DOM,提取视频 URL
2. API 请求: 向后端服务发送视频链接和格式选项
3. 进度跟踪: 使用 XMLHttpRequest 监听 progress 事件
4. 文件保存: 通过 Blob 对象和 <a> 标签触发下载

// 自动检测 YouTube 暗色模式
const isDarkMode = document.documentElement.hasAttribute('dark');
panel.style.backgroundColor = isDarkMode 
  ? 'rgba(33, 33, 33, 0.95)' 
  : 'rgba(255, 255, 255, 0.95)';

• Base URL: https://ytd.suck-dick.tech/api/v1
• 请求端点: /request
• 方法: POST
• 请求体:

  {
    "url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "format": "mp4",
    "quality": "1080p"
  }
  

{
  "success": true,
  "download_url": "https://cdn.example.com/video.mp4",
  "filename": "video_title.mp4",
  "filesize": 52428800
}

// 防止 XSS 攻击的 CSP 兼容实现
if (window.trustedTypes && trustedTypes.createPolicy) {
  trustedTypes.createPolicy('default', {
    createHTML: (string) => string,
    createScriptURL: (string) => string,
    createScript: (string) => string,
  });
}

• 仅允许来自可信 CDN 的外部资源
• 禁用 eval() 和内联脚本
• 使用 nonce 或 hash 验证注入的样式

1. 导航到 YouTube 视频页面

   • 打开任意 YouTube 视频 (例如: https://www.youtube.com/watch?v=dQw4w9WgXcQ)

2. 定位下载按钮

   • 在视频播放器右下角控制栏,找到带有 📥 图标的下载按钮
   • 按钮位于全屏按钮和设置按钮之间

3. 选择下载选项

   • 点击下载按钮,展开下载选项面板
   • 面板分为两个标签页:
     • 视频: 选择清晰度 (8K ~ 360p)
     • 音频: 选择格式 (MP3/FLAC/WAV)

4. 开始下载

   • 点击所需格式按钮
   • 观察进度条显示下载进度
   • 下载完成后文件将自动保存到浏览器默认下载目录

┌─────────────────────────────────────┐
│  📥 Download Panel                  │
├─────────────────────────────────────┤
│  [视频] [音频]                       │
│                                     │
│  🎥 视频质量:                        │
│  [8K]  [4K]  [2K]  [1080p]         │
│  [720p] [480p] [360p]              │
│                                     │
│  ━━━━━━━━━━━ 75% ━━━━━━━━━━━       │
│  Downloading: 38.4 MB / 51.2 MB    │
└─────────────────────────────────────┘

• 问题: 点击下载按钮无响应
• 解决方案:
  1. 刷新 YouTube 页面,等待视频完全加载
  2. 检查浏览器控制台 (F12) 是否有错误信息
  3. 确认视频不是受版权保护的直播或会员专享内容

• 问题: 下载进度长时间停留在某个百分比
• 解决方案:
  1. 检查网络连接是否稳定
  2. 关闭下载面板,重新点击下载按钮
  3. 尝试选择较低的视频清晰度

• 问题: 浏览器工具栏没有扩展图标
• 解决方案:
  1. 在 chrome://extensions/ 确认扩展已启用
  2. 点击拼图图标 🧩,将扩展固定到工具栏
  3. 重启浏览器

如果您发现 bug 或有功能建议:

1. 前往 Issues 页面
2. 使用以下模板创建新 issue:

**问题描述**
简要说明问题...

**复现步骤**
1. 打开 YouTube 视频...
2. 点击下载按钮...
3. 观察到错误...

**预期行为**
描述您期望发生的情况...

**环境信息**
- 浏览器: Chrome 120.0.6099.109
- 操作系统: Windows 11
- 扩展版本: 1.3

**截图**
如果适用,添加截图帮助说明问题

1. Fork 仓库

git clone https://github.com/yourusername/youtube-downloader.git
cd youtube-downloader

2. 创建功能分支

git checkout -b feature/your-feature-name

3. 进行更改

   • 遵循现有代码风格
   • 添加必要的注释
   • 确保 TypeScript 编译通过: npm run build

4. 提交代码

git add .
git commit -m "feat: add amazing feature"

5. 推送并创建 PR

git push origin feature/your-feature-name

然后在 GitHub 上创建 Pull Request

• 使用 TypeScript 严格模式
• 遵循 Aether 设计系统 (圆角、主题适配)
• 所有用户可见文本使用中文
• 提交信息遵循 Conventional Commits

本项目采用 MIT License 开源许可证。

MIT License

Copyright (c) 2025 Andy Zhang

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...

⚠️ 重要提示

1. 合法使用: 本扩展仅供个人学习和研究使用。请尊重内容创作者的版权。

2. 版权合规:

   • 仅下载您拥有版权或已获授权的内容
   • 不得用于商业目的或二次分发
   • 遵守 YouTube 服务条款和当地法律法规

3. 免责条款:

   • 作者不对使用本软件造成的任何直接或间接损失负责
   • 用户需自行承担使用本软件的法律风险
   • 本软件按 "原样" 提供,不提供任何形式的保证

4. 服务可用性:

   • 后端 API 服务由第三方提供,可用性不作保证
   • YouTube 页面结构变更可能导致功能失效
   • 建议定期更新到最新版本

• Issues: GitHub Issues
• Email: your.email@example.com
• Discord: 加入社区

---