@king-3/file-kit

🔧 多功能文件工具箱 — Base64 转换 · 视频转音频 · 文件加密/解密

✨ 核心功能

• 📄 Base64 转换 - 文件 ↔ Base64 JSON，支持双向转换和完整还原
• 🎵 视频转音频 - 从视频中提取音频轨道，支持 5 种格式和 3 种质量级别
• 🔐 文件加密/解密 - 基于 AES-256-GCM 的军事级加密，确保数据安全

📦 安装

全局安装（推荐）

# 使用 pnpm
pnpm install @king-3/file-kit -g

# 使用 npm
npm install @king-3/file-kit -g

# 使用 yarn
yarn global add @king-3/file-kit

本地安装

pnpm install @king-3/file-kit --save-dev

🚀 快速开始

命令行模式

# 查看帮助
fkt --help

# 查看版本
fkt --version

# 启动交互模式
fkt -i

交互模式

交互模式提供友好的可视化界面，一步步引导您完成操作：

fkt -i

进入交互模式后，你可以通过方向键选择以下功能：

• 📦 文件转 Base64
• 🔄 Base64 还原文件
• 🎵 视频提取音频
• 🔐 文件加密
• 🔓 文件解密

📖 功能详解

1️⃣ Base64 转换

将任意文件编码为 Base64 格式并保存为 JSON 文件，适用于 API 传输、数据库存储等场景。

基础用法

fkt base64 <文件路径> [选项]

使用示例

# 转换文本文件
fkt base64 document.txt

# 转换图片
fkt base64 photo.jpg

# 转换 PDF
fkt base64 report.pdf

# 指定输出目录
fkt base64 file.txt -o ./output

输出格式

生成的 JSON 文件格式如下：

{
  "type": "base64",
  "createdAt": "2024-12-16 10:30:45",
  "file": {
    "name": "document.txt",
    "extension": ".txt",
    "size": 1024,
    "base64": "SGVsbG8gV29ybGQh..."
  }
}

命令选项

| 选项 | 描述 | | --------------------- | ------------------------------ | | -o, --output <path> | 指定输出目录（默认：当前目录） | | -h, --help | 显示帮助信息 |

2️⃣ Base64 还原

从 Base64 JSON 文件恢复原始文件。

基础用法

fkt restore <JSON文件路径> [选项]

使用示例

# 还原文件（默认输出到当前目录）
fkt restore archive.base64.json

# 指定输出目录
fkt restore archive.base64.json -o ./restored

特性

• ✅ 保留原始文件大小信息
• ✅ 显示原始创建时间戳
• ✅ 验证 JSON 格式完整性

命令选项

| 选项 | 描述 | | --------------------- | ------------------------------ | | -o, --output <path> | 指定输出目录（默认：当前目录） | | -h, --help | 显示帮助信息 |

3️⃣ 视频转音频

从视频文件中提取音频轨道，支持多种格式和质量选项。底层使用 FFmpeg 进行专业级音视频处理。

基础用法

fkt video-to-audio <视频文件> [选项]
# 或使用别名
fkt v2a <视频文件> [选项]

支持的音频格式

| 格式 | 扩展名 | 编码器 | 特点 | 适用场景 | | -------- | ------- | ---------- | -------------- | --------------- | | MP3 | .mp3 | libmp3lame | 最佳兼容性 | 日常使用、分享 | | AAC | .m4a | aac | Apple 生态优化 | iOS/macOS 设备 | | FLAC | .flac | flac | 无损压缩 | 音乐收藏、归档 | | ALAC | .m4a | alac | Apple 无损格式 | iTunes/iOS 无损 | | WAV | .wav | pcm_s16le | 未压缩原始音频 | 专业音频编辑 |

质量选项

| 质量 | MP3 | AAC | FLAC | 说明 | | ---------- | ---- | ---- | ------ | ---------------- | | low | 128k | 128k | 级别 0 | 快速，文件小 | | medium | 192k | 192k | 级别 5 | 平衡质量（推荐） | | high | 320k | 256k | 级别 8 | 最佳质量 |

使用示例

基础转换

# 交互式选择格式和质量
fkt v2a video.mp4

指定格式和质量

# 转换为高质量 MP3
fkt v2a video.mp4 -f mp3 -q high

# 转换为中等质量 AAC
fkt v2a video.mp4 -f aac -q medium

# 转换为无损 FLAC
fkt v2a video.mp4 -f flac -q high

指定输出路径

# 指定输出目录
fkt v2a video.mp4 -o ./audio -f mp3 -q high

# 输出文件: ./audio/video.mp3

批量转换

# 使用 shell 循环批量转换
for file in *.mp4; do
  fkt v2a "$file" -f mp3 -q high
done

进度显示

转换过程中会实时显示进度：

⠋ 正在提取音频 45%

完成后显示输出路径：

✔ 音频已提取到: ./video.mp3

命令选项

| 选项 | 描述 | | --------------------- | --------------------------------- | | -f, --format <fmt> | 音频格式（mp3/aac/flac/alac/wav） | | -q, --quality <qlt> | 音频质量（low/medium/high） | | -o, --output <path> | 输出目录（默认：视频所在目录） | | -h, --help | 显示帮助信息 |

4️⃣ 文件加密

使用 AES-256-GCM 算法对文件进行加密，生成加密的 JSON 文件。

加密算法

• 算法：AES-256-GCM（Galois/Counter Mode）
• 密钥派生：PBKDF2-SHA256（100,000 次迭代）
• 初始化向量：16 字节随机生成
• 盐值：32 字节随机生成
• 认证标签：GCM 模式自动生成，确保数据完整性

基础用法

fkt encrypt <文件路径> [选项]

使用示例

# 交互式加密（会提示输入密码）
fkt encrypt secret.txt

# 命令行指定密码
fkt encrypt secret.txt -p myPassword123

# 指定输出目录
fkt encrypt secret.txt -o ./encrypted -p myPassword123

输出格式

生成的加密 JSON 文件格式：

{
  "type": "crypto",
  "algorithm": "aes-256-gcm",
  "createdAt": "2024-12-16 10:30:45",
  "file": {
    "name": "secret.txt",
    "extension": ".txt",
    "size": 2048,
    "iv": "base64_encoded_iv",
    "authTag": "base64_encoded_auth_tag",
    "salt": "base64_encoded_salt",
    "encrypted": "base64_encoded_data"
  }
}

安全建议

• ⚠️ 请妥善保管密码，丢失后无法恢复文件
• 🔒 密码长度至少 6 位，建议使用强密码
• 💾 建议备份加密文件到安全位置
• 🔑 不要在命令行直接暴露密码（使用交互模式）

命令选项

| 选项 | 描述 | | ---------------------- | -------------------------------- | | -p, --password <pwd> | 加密密码（建议使用交互模式输入） | | -o, --output <path> | 输出目录（默认：当前目录） | | -h, --help | 显示帮助信息 |

5️⃣ 文件解密

从加密的 JSON 文件中解密并还原原始文件。

基础用法

fkt decrypt <加密JSON文件> [选项]

使用示例

# 交互式解密（会提示输入密码）
fkt decrypt secret.crypto.json

# 命令行指定密码
fkt decrypt secret.crypto.json -p myPassword123

# 指定输出目录
fkt decrypt secret.crypto.json -o ./decrypted -p myPassword123

特性

• ✅ 自动验证密码正确性
• ✅ 验证数据完整性（通过 GCM 认证标签）
• ✅ 还原原始文件名和扩展名
• ✅ 密码错误时友好提示

错误处理

如果密码错误，会显示以下提示：

✖ 解密失败：密码错误或文件已损坏

命令选项

| 选项 | 描述 | | ---------------------- | -------------------------------- | | -p, --password <pwd> | 解密密码（建议使用交互模式输入） | | -o, --output <path> | 输出目录（默认：当前目录） | | -h, --help | 显示帮助信息 |

🎮 命令参考

全局选项

| 选项 | 别名 | 描述 | | --------------- | ---- | ------------ | | --help | -h | 显示帮助信息 | | --version | -v | 显示版本号 | | --interactive | -i | 启动交互模式 |

命令列表

| 命令 | 别名 | 描述 | | ------------------------ | ----- | --------------- | | base64 <input> | - | 文件转 Base64 | | restore <input> | - | Base64 还原文件 | | video-to-audio <input> | v2a | 视频提取音频 | | encrypt <input> | - | 文件加密 | | decrypt <input> | - | 文件解密 |

🎯 使用场景

场景 1：文件分享与存储

问题：需要将二进制文件转换为文本格式，便于在 API 或数据库中存储和传输。

解决方案：

# 转换为 Base64
fkt base64 document.pdf -o ./archive

# 通过 API 传输或存储到数据库
# ...

# 需要时还原
fkt restore ./archive/document.json -o ./restored

场景 2：敏感文件加密存储

问题：需要安全存储敏感文件，如合同、身份证件等。

解决方案：

# 加密文件
fkt encrypt contract.pdf -o ./encrypted

# 安全传输或备份加密文件
# ...

# 需要时解密
fkt decrypt ./encrypted/contract.crypto.json -o ./restored

场景 3：视频素材音频提取

问题：从视频素材中提取音频用于后期制作或音乐收藏。

解决方案：

# 提取高质量 MP3（日常使用）
fkt v2a interview.mp4 -f mp3 -q high -o ./audio

# 提取无损 FLAC（专业编辑）
fkt v2a concert.mp4 -f flac -q high -o ./audio

# Apple 设备使用 ALAC
fkt v2a music_video.mp4 -f alac -q high -o ./audio

场景 4：自动化工作流

问题：需要批量处理多个文件。

解决方案：

# 批量加密
for file in *.txt; do
  fkt encrypt "$file" -p myPassword123 -o ./encrypted
done

# 批量转换视频
for video in *.mp4; do
  fkt v2a "$video" -f mp3 -q high -o ./audio
done

📊 架构设计

┌─────────────────────────────────────┐
│         CLI 层 (cli.ts)             │  ← Citty 命令行解析
├─────────────────────────────────────┤
│       Config 层 (config/)           │  ← 配置管理
│  • defaults.ts                      │     - CLI 默认配置
│  • audio-formats.ts                 │     - 音频格式配置
│  • crypto-algorithm.ts              │     - 加密算法配置
├─────────────────────────────────────┤
│      Commands 层 (commands/)        │  ← 命令处理
│  • base64.ts                        │     - Base64 转换命令
│  • restore.ts                       │     - Base64 还原命令
│  • video-to-audio.ts                │     - 视频转音频命令
│  • encrypt.ts                       │     - 文件加密命令
│  • decrypt.ts                       │     - 文件解密命令
├─────────────────────────────────────┤
│        Core 层 (core/)              │  ← 核心业务逻辑
│  • base64.ts                        │     - Base64 编解码
│  • crypto.ts                        │     - 加密解密算法
│  • extract.ts                       │     - 视频音频提取
├─────────────────────────────────────┤
│       Utils 层 (utils/)             │  ← 通用工具函数
│  • errors.ts                        │     - 错误处理
│  • helpers.ts                       │     - 命令助手
│  • file.ts                          │     - 文件操作
│  • logger.ts                        │     - 日志输出
│  • prompts.ts                       │     - 交互提示
│  • time.ts                          │     - 时间格式化
└─────────────────────────────────────┘

🛠️ 技术栈

| 技术 | 描述 | 用途 | | ------------------ | ----------------------- | ------------------ | | Citty | 现代化命令行框架 | CLI 路由和参数解析 | | Clack Prompts | 美观的交互式 CLI 提示库 | 用户交互界面 | | FFmpeg | 强大的多媒体处理工具 | 视频音频转换 | | Ansis | 轻量级终端颜色库 | 终端输出美化 | | Node.js Crypto | Node.js 内置加密模块 | AES-256-GCM 加密 |

⚙️ 配置

环境变量

# 开启调试模式（显示详细错误堆栈）
DEBUG=1 fkt base64 file.txt

# 指定 FFmpeg 路径（如果未在 PATH 中）
FFMPEG_PATH=/usr/local/bin/ffmpeg fkt v2a video.mp4

🔧 常见问题

Q1: FFmpeg 相关错误

错误：FFmpeg 未找到 或 spawn ffmpeg ENOENT

解决方案：

npm install @ffmpeg-installer/ffmpeg

Q2: 视频转音频进度卡住

原因：视频文件损坏或格式不支持

解决方案：

1. 检查视频文件是否完整：

ffmpeg -i video.mp4

2. 尝试使用其他格式：

fkt v2a video.mp4 -f mp3

3. 检查文件权限：

ls -la video.mp4

Q3: Base64 文件过大

原因：Base64 编码会增加约 33% 的体积

建议：

• 对于大文件（>10MB），考虑先压缩再编码
• Base64 更适合小型文件或需要文本传输的场景
• 对于大型文件，建议使用加密功能而非 Base64

Q4: 加密/解密失败

问题：密码错误或文件损坏

解决方案：

# 确保密码正确（区分大小写）
fkt decrypt file.crypto.json -p correctPassword

# 检查 JSON 文件完整性
cat file.crypto.json | jq

# 验证文件类型
fkt decrypt file.crypto.json  # 使用交互模式

Q5: 权限错误

错误：EACCES: permission denied

解决方案：

# 检查文件权限
ls -la file.txt

# 修改权限
chmod 644 file.txt

# 检查目录权限
chmod 755 ./output

Q6: 内存不足（大文件处理）

问题：处理大文件时内存溢出

解决方案：

# 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" fkt base64 large-file.zip

📝 开发

本地开发

# 克隆仓库
git clone https://github.com/coderking3/file-kit.git
cd file-kit

# 安装依赖
pnpm install

# 开发模式运行
pnpm dev base64 test.txt

# 类型检查
pnpm typecheck

# 代码格式化
pnpm format

# 代码检查
pnpm lint

# 构建
pnpm build

项目结构

file-kit/
├── src/
│   ├── cli.ts              # CLI 入口
│   ├── config/             # 配置层
│   │   ├── defaults.ts
│   │   ├── audio-formats.ts
│   │   └── crypto-algorithm.ts
│   ├── commands/           # 命令层
│   │   ├── index.ts
│   │   ├── base64.ts
│   │   ├── restore.ts
│   │   ├── video-to-audio.ts
│   │   ├── encrypt.ts
│   │   └── decrypt.ts
│   ├── core/               # 核心逻辑层
│   │   ├── base64.ts
│   │   ├── crypto.ts
│   │   └── extract.ts
│   ├── utils/              # 工具函数层
│   │   ├── errors.ts
│   │   ├── file.ts
│   │   ├── helpers.ts
│   │   ├── logger.ts
│   │   ├── prompts.ts
│   │   └── time.ts
│   └── types/              # 类型定义
│       └── index.ts
├── bin/
│   └── cli.mjs             # 可执行文件
├── package.json
├── tsconfig.json
└── README.md

发布流程

# 更新版本号
pnpm release

# 构建并发布
pnpm build
pnpm publish

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 开启 Pull Request

贡献指南

• 遵循现有代码风格
• 添加适当的测试
• 更新相关文档
• 确保所有测试通过

📄 许可证

MIT License © 2024 King3

🔗 相关链接

• 📦 NPM 包
• 🐙 GitHub 仓库
• 🐛 问题反馈
• 📋 更新日志

💬 联系方式

• 作者：King3
• 邮箱：[email protected]
• 问题反馈：GitHub Issues