Video to Audio Converter - 快速开始指南

🚀 项目概述

这是一个基于 Next.js 和 FFmpeg.wasm 的视频转音频工具网站，所有处理都在用户浏览器中完成，无需上传文件到服务器。

📋 前置要求

Node.js: 18.0 或更高版本
pnpm: 8.0 或更高版本
Git: 用于版本控制

检查环境

# 检查 Node.js 版本
node --version

# 检查 pnpm 版本
pnpm --version

# 如果没有安装 pnpm，请先安装
npm install -g pnpm

🛠️ 项目创建

方法一：使用自动脚本（推荐）

下载启动脚本

# 确保脚本有执行权限
chmod +x setup-project.sh

# 运行脚本
./setup-project.sh

cd video-to-audio-converter

方法二：手动创建

创建 Next.js 项目

pnpm create next-app@latest video-to-audio-converter --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd video-to-audio-converter

安装依赖

# 核心依赖
pnpm add @ffmpeg/ffmpeg @ffmpeg/util
pnpm add @supabase/supabase-js
pnpm add next-intl
pnpm add lucide-react
pnpm add react-dropzone

# 开发依赖
pnpm add -D @types/node @types/react @types/react-dom
pnpm add -D tailwindcss-animate
pnpm add -D @testing-library/react @testing-library/jest-dom

初始化 shadcn/ui

pnpm dlx shadcn@latest init

安装 UI 组件

pnpm dlx shadcn@latest add button card label select slider progress input textarea dialog toast

⚙️ 环境配置

1. 创建环境变量文件

在项目根目录创建 .env.local 文件：

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url_here
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key_here

# Next.js Configuration
NEXTAUTH_SECRET=your_nextauth_secret_here
NEXTAUTH_URL=http://localhost:3000

# App Configuration
NEXT_PUBLIC_APP_NAME=Video to Audio Converter
NEXT_PUBLIC_APP_URL=http://localhost:3000

2. 配置 Supabase

创建 Supabase 项目
- 访问 https://supabase.com
- 注册并创建新项目
- 等待项目初始化完成
获取项目配置
- 进入项目设置 → API
- 复制 Project URL 和 anon public 密钥
- 更新 .env.local 文件
创建数据库表

在 Supabase SQL 编辑器中运行以下 SQL：

-- 用户表
CREATE TABLE my_users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  last_login TIMESTAMP
);

-- 转换历史表
CREATE TABLE my_conversions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES my_users(id),
  original_filename VARCHAR NOT NULL,
  input_format VARCHAR NOT NULL,
  output_format VARCHAR NOT NULL,
  file_size BIGINT NOT NULL,
  conversion_time INTEGER,
  created_at TIMESTAMP DEFAULT NOW()
);

-- 启用 RLS (Row Level Security)
ALTER TABLE my_users ENABLE ROW LEVEL SECURITY;
ALTER TABLE my_conversions ENABLE ROW LEVEL SECURITY;

-- 创建策略
CREATE POLICY "Users can view own data" ON my_users
  FOR SELECT USING (auth.uid() = id);

CREATE POLICY "Users can insert own data" ON my_users
  FOR INSERT WITH CHECK (auth.uid() = id);

CREATE POLICY "Users can view own conversions" ON my_conversions
  FOR SELECT USING (auth.uid() = user_id);

CREATE POLICY "Users can insert own conversions" ON my_conversions
  FOR INSERT WITH CHECK (auth.uid() = user_id);

3. 配置 FFmpeg 文件

mkdir -p public/ffmpeg

下载 FFmpeg 核心文件

从 FFmpeg.wasm CDN 下载文件到 public/ffmpeg/ 目录：

# 下载核心文件
curl -o public/ffmpeg/ffmpeg-core.js https://unpkg.com/@ffmpeg/core@0.12.6/dist/umd/ffmpeg-core.js
curl -o public/ffmpeg/ffmpeg-core.wasm https://unpkg.com/@ffmpeg/core@0.12.6/dist/umd/ffmpeg-core.wasm

🏗️ 项目结构

确保项目结构如下：

video-to-audio-converter/
├── src/
│   ├── app/
│   │   ├── (auth)/
│   │   │   ├── login/
│   │   │   └── register/
│   │   ├── api/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   ├── ui/
│   │   ├── file-upload.tsx
│   │   ├── converter.tsx
│   │   ├── progress.tsx
│   │   └── audio-player.tsx
│   ├── lib/
│   │   ├── ffmpeg.ts
│   │   ├── supabase.ts
│   │   └── utils.ts
│   ├── types/
│   │   └── index.ts
│   └── hooks/
│       └── use-converter.ts
├── public/
│   └── ffmpeg/
│       ├── ffmpeg-core.js
│       └── ffmpeg-core.wasm
├── .env.local
├── next.config.ts
├── tailwind.config.ts
├── tsconfig.json
└── package.json

🚀 启动开发服务器

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

访问 http://localhost:3000 查看应用。

🧪 测试功能

基本功能测试

文件上传测试
- 准备一个测试视频文件（MP4 格式，小于 100MB）
- 拖拽或点击上传文件
- 验证文件格式检测
转换功能测试
- 选择输出格式（如 MP3）
- 调整质量参数
- 点击转换按钮
- 验证转换进度显示
下载功能测试
- 转换完成后预览音频
- 点击下载按钮
- 验证文件下载

错误处理测试

不支持的文件格式
- 尝试上传 .txt 文件
- 验证错误提示
文件过大
- 尝试上传超过限制的文件
- 验证错误提示
网络错误
- 断开网络连接
- 验证错误处理

🔧 常见问题解决

1. FFmpeg 加载失败

问题: Failed to load FFmpeg core

解决方案:

检查 public/ffmpeg/ 目录是否存在
验证 FFmpeg 文件是否正确下载
检查浏览器控制台错误信息

2. 跨域错误

问题: SharedArrayBuffer is not defined

解决方案:

确保 next.config.ts 中配置了正确的 CORS 头
重启开发服务器
检查浏览器是否支持 SharedArrayBuffer

3. 类型错误

问题: TypeScript 编译错误

解决方案:

# 检查类型
pnpm type-check

# 修复 ESLint 错误
pnpm lint --fix

4. 依赖安装失败

问题: pnpm 安装依赖失败

解决方案:

# 清理缓存
pnpm store prune

# 重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

📦 构建和部署

本地构建测试

# 构建生产版本
pnpm build

# 启动生产服务器
pnpm start

Vercel 部署

推送代码到 GitHub

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/video-to-audio-converter.git
git push -u origin main

在 Vercel 中部署
- 访问 https://vercel.com
- 导入 GitHub 项目
- 配置环境变量
- 部署
配置环境变量 在 Vercel 项目设置中添加：
- NEXT_PUBLIC_SUPABASE_URL
- NEXT_PUBLIC_SUPABASE_ANON_KEY
- NEXTAUTH_SECRET
- NEXTAUTH_URL

🔍 性能优化

1. 代码分割

// 动态导入 FFmpeg 组件
const FFmpegConverter = dynamic(() => import("@/components/ffmpeg-converter"), {
  loading: () => <div>Loading converter...</div>,
  ssr: false,
});

2. 缓存策略

// 缓存 FFmpeg 实例
const ffmpegInstance = useMemo(() => new FFmpeg(), []);

3. 错误边界

class ConversionErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    console.error("Conversion error:", error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return <div>Something went wrong with the conversion.</div>;
    }

    return this.props.children;
  }
}

📚 学习资源

🤝 贡献指南

Fork 项目
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🎉 恭喜！您已经成功搭建了 Video to Audio Converter 项目！

现在您可以开始开发新功能，优化用户体验，或者部署到生产环境了。