@vtxf/qshell

七牛云 Qshell 命令行工具的 npm 封装包，支持按需下载，轻量高效。

qshell 是七牛云官方提供的命令行工具，用于管理和操作七牛云对象存储 Kodo 及其他服务。本项目提供智能的按需下载机制，首次使用时自动下载对应平台的二进制文件。

特性

• ✅ 智能下载：首次运行时自动检测平台并下载对应二进制文件
• ✅ 多源支持：支持七牛官方 CDN、GitHub Releases 等多个下载源
• ✅ 跨平台支持：支持 Windows、macOS、Linux 共 9 个平台
• ✅ 轻量级：npm 包仅包含 JavaScript 代码，几 KB 大小
• ✅ 自动更新：支持下载最新版本的官方二进制文件
• ✅ 零依赖：只使用 Node.js 原生模块
• ✅ 官方二进制：直接使用七牛云官方发布的二进制文件
• ✅ 智能重试：下载失败时自动尝试备用源

支持的平台

平台	架构	平台键
Windows	32位 (x86)	windows-386
Windows	64位 (amd64)	windows-amd64
Windows	ARM	windows-arm
macOS	Intel	mac-amd64
macOS	Apple Silicon	mac-arm64
Linux	32位 (x86)	linux-386
Linux	64位 (amd64)	linux-amd64
Linux	ARM	linux-arm
Linux	ARM64	linux-arm64

安装

使用 npx（推荐）

无需安装，直接使用：

npx @vtxf/qshell -v

首次运行时会自动下载对应平台的二进制文件。

全局安装

npm install -g @vtxf/qshell

安装后可以直接使用 qshell 命令：

qshell -v

项目中使用

npm install @vtxf/qshell

然后使用 npx：

npx @vtxf/qshell -h

使用示例

首次使用（自动下载）

npx @vtxf/qshell -v

首次运行时会显示下载进度：

🔍 Binary not found, initiating download...

📡 Trying source: Qiniu CDN (https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-...)
⏳ Downloading: 45.2% (5.4MB/12.0MB) - 1250KB/s - 5s remaining
✅ Download completed!
📦 Extracting archive...
✅ Extraction completed!
✅ Successfully installed qshell to /path/to/bin/windows-amd64/qshell.exe

查看版本

npx @vtxf/qshell -v

查看帮助

npx @vtxf/qshell -h

设置账号密钥

npx @vtxf/qshell account <AccessKey> <SecretKey> <name>

账号管理

# 列出所有账号
npx @vtxf/qshell user ls

# 切换账号
npx @vtxf/qshell user cu <name>

查询存储空间

# 获取所有空间名称
npx @vtxf/qshell buckets

# 查看空间信息
npx @vtxf/qshell bucket <bucket-name>

# 获取空间关联域名
npx @vtxf/qshell domains <bucket-name>

上传文件

# 表单上传
npx @vtxf/qshell fput <bucket> <key> <localFile>

# 分片上传
npx @vtxf/qshell rput <bucket> <key> <localFile>

# 批量同步上传（配置式）
npx @vtxf/qshell qupload <config-file>

# 批量同步上传（命令式）
npx @vtxf/qshell qupload2 ...

下载文件

# 下载单个文件
npx @vtxf/qshell get <bucket> <key>

# 批量同步下载
npx @vtxf/qshell qdownload <config-file>

文件管理

# 列举空间文件
npx @vtxf/qshell listbucket <bucket>

# 查询文件信息
npx @vtxf/qshell stat <bucket> <key>

# 删除文件
npx @vtxf/qshell delete <bucket> <key>

# 移动/重命名文件
npx @vtxf/qshell move <srcBucket> <srcKey> <destBucket> <destKey>

# 复制文件
npx @vtxf/qshell copy <srcBucket> <srcKey> <destBucket> <destKey>

CDN 刷新

# 刷新 CDN 外链或目录
npx @vtxf/qshell cdnrefresh <dirs-or-urls-file>

# 预取 CDN 外链
npx @vtxf/qshell cdnprefetch <urls-file>

下载源优先级

系统按以下优先级尝试下载源：

1. 七牛云官方 CDN（最快，推荐）

   • 下载地址：https://kodo-toolbox-new.qiniu.com/
   • 自动提供最新版本

2. GitHub Releases（备用源）

   • 下载地址：https://github.com/qiniu/qshell/releases
   • 可指定特定版本

如某个源下载失败，系统会自动尝试下一个源。

二进制文件存储

下载的二进制文件存储位置：

• Windows: node_modules/@vtxf/qshell/bin/windows-amd64/qshell.exe
• macOS Intel: node_modules/@vtxf/qshell/bin/mac-amd64/qshell
• macOS Apple Silicon: node_modules/@vtxf/qshell/bin/mac-arm64/qshell
• Linux: node_modules/@vtxf/qshell/bin/linux-amd64/qshell

手动管理二进制文件

如果需要重新下载或更换版本：

# 删除现有二进制文件
rm -rf node_modules/@vtxf/qshell/bin/*/

# 下次运行时会自动重新下载
npx @vtxf/qshell -v

版本说明

本包当前封装版本：qshell v2.19.2

建议使用 v2.8.0 及以上版本。

故障排除

下载失败

如果遇到下载失败，请检查：

1. 网络连接：确保能够访问互联网
2. 防火墙设置：某些网络可能阻止外网访问
3. 代理配置：如使用代理，确保 Node.js 环境变量正确配置
4. 重试机制：系统会自动尝试多个下载源

找不到二进制文件

如果出现 "找不到对应平台的 qshell 二进制文件" 错误：

1. 删除 bin/ 目录内容，重新下载
2. 检查磁盘空间是否充足
3. 查看错误信息中的具体原因

权限错误（Unix 系统）

在 macOS 或 Linux 上，如果遇到权限错误：

chmod +x node_modules/@vtxf/qshell/bin/*/qshell

其他问题

如遇到其他问题，请访问：

• qshell GitHub Issues
• 七牛云官方文档

包大小对比

传统方案（内置所有平台）：

• npm 包大小：较大（包含 9 个平台二进制）
• 下载时间：较慢

按需下载方案（当前）：

• npm 包大小：~几 KB
• 下载时间：快速
• 磁盘占用：仅当前平台

开发

项目结构

@vtxf/qshell/
├── bin/              # 二进制文件目录（运行时下载）
│   ├── windows-386/    # Windows 32位
│   ├── windows-amd64/  # Windows 64位
│   ├── windows-arm/    # Windows ARM
│   ├── mac-amd64/      # macOS Intel
│   ├── mac-arm64/      # macOS Apple Silicon
│   ├── linux-386/      # Linux 32位
│   ├── linux-amd64/    # Linux 64位
│   ├── linux-arm/      # Linux ARM
│   └── linux-arm64/    # Linux ARM64
├── lib/              # JavaScript 封装代码
│   ├── main.js       # CLI 入口点
│   ├── platform.js   # 平台检测模块
│   ├── executor.js   # 二进制执行器
│   └── downloader.js # 多源下载器
├── package.json
└── README.md

本地测试

# 本地链接
npm link

# 测试（会触发首次下载）
qshell -v

许可证

MIT License

本项目使用 MIT 许可证。qshell 二进制文件的使用遵循七牛云官方许可证。

致谢

• 七牛云官方 qshell 项目

链接

• qshell GitHub
• qshell 官方文档
• qshell 命令详细文档

---

注意：本项目为第三方封装的 npm 包，非七牛云官方产品。如有问题建议先到 qshell 官方仓库 查找解决方案。