开源项目分享：123 网盘 SDK - npm包已发布

前言

大家好！今天想和大家分享一个我最近开源的项目：123 网盘 SDK 。这个项目前几天在 GitHub 开源，现在已经发布到 NPM，可以通过 npm i @ked3/pan123-sdk 直接安装使用。

项目背景：为什么要开发这个 SDK？

在使用 123 网盘官方 API 的过程中，我发现文件上传流程异常复杂，需要调用多个接口：

创建文件
获取上传地址和上传分片
列举已上传分片
完成上传
异步轮询获取上传结果

这种复杂的流程对开发者来说非常不友好，每次都要重复编写大量的代码。于是我决定开发一个简单易用的 SDK，让开发者能够通过几行代码就完成文件操作。

✨ 核心特性

经过不断的迭代和完善，这个 SDK 现在具备了以下核心特性：

🚀 api更新

上传文件
获取文件夹内容
获取文件详情（2025-05-29）
获取文件下载链接
在线解压文件
获取直链链接 ,启用直链,禁用直链（2025-06-02） v1.0.7

📦 智能分片上传

自动处理大文件分片上传
上传进度跟踪

🔄 秒传检测

支持文件 MD5 校验
智能识别重复文件
提升上传效率

🌐 多环境兼容

支持 CommonJS 和 ES Module
Node.js 环境原生支持
完善的 TypeScript 类型定义

🔐 安全可靠

基于 clientId 和 clientSecret 的安全认证
自动 token 管理和刷新
内置错误重试机制

📦 安装使用

安装

bash 复制代码

npm install @ked3/pan123-sdk

基础使用

ES Module 方式

javascript 复制代码

import Pan123SDK from "@ked3/pan123-sdk";

const sdk = new Pan123SDK({
  clientId: "your_client_id",
  clientSecret: "your_client_secret",
});

// 初始化 token
await sdk.initToken();

// 上传文件
const uploadResult = await sdk.uploadFile("./example.zip", {
  parentFileID: 0, // 父目录ID，0表示根目录
  containDir: false, // 是否包含目录结构
  duplicate: 1, // 重名处理策略：1-重命名，2-覆盖，3-跳过
});

// 获取文件列表
const fileList = await sdk.getFileList({
  parentFileId: 0,
  limit: 100,
  searchData: "",
  searchMode: 0,
  lastFileId: 0,
});

// 获取下载链接
const downloadUrl = await sdk.getFileDownloadUrl({
  fileId: "123456789",
});

CommonJS 方式

javascript 复制代码

const Pan123SDK = require("@ked3/pan123-sdk");

const sdk = new Pan123SDK({
  clientId: "xxx",
  clientSecret: "xxx",
});

async function main() {
  await sdk.initToken();

  const uploadResult = await sdk.uploadFile(filePath, {
    parentFileID: 14439872,
    containDir: false,
    duplicate: 2,
  });
}

main();

🔥 实用功能演示

在线解压功能

javascript 复制代码

// 解压 ZIP 文件到指定文件夹
const result = await sdk.zipFile({
  fileId: "123456789", // ZIP文件ID
  folderId: "987654321", // 解压目标文件夹ID
});

直链管理

javascript 复制代码

// 启用文件直链
await sdk.enableDirectLink(fileId);

// 获取直链地址
const directUrl = await sdk.getDirectLink(fileId);

// 禁用直链
await sdk.disableDirectLink(fileId);

🛠️ 技术实现亮点

1. 智能分片上传

SDK 内部实现了智能的分片上传逻辑，能够：

根据文件大小自动决定是否分片
并发上传多个分片提升速度
自动重试失败的分片
实时反馈上传进度

2. Token 自动管理

自动获取和刷新 access_token
内存缓存避免重复请求
过期自动续期，无需手动处理

3. 错误处理机制

网络错误自动重试
详细的错误信息返回
优雅的异常处理

🤝 参与贡献

这是一个开源项目，非常欢迎大家参与贡献：

报告问题: 在 GitHub Issues 中反馈 bug
功能建议: 提出新的功能需求
代码贡献: 提交 Pull Request
文档完善: 帮助改进文档和示例

总结

123 网盘 SDK 的诞生源于实际开发中的痛点，通过简化复杂的 API 调用流程，让开发者能够更专注于业务逻辑的实现。

如果你正在开发需要文件存储功能的应用，或者对 123 网盘 API 感兴趣，欢迎试用这个 SDK。相信它能为你的开发工作带来便利。

快速开始：

bash 复制代码

npm install @ked3/pan123-sdk

项目地址： $GitHub Repository$ NPM 包： @ked3/pan123-sdk

如果这个项目对你有帮助，别忘了给个 ⭐ Star 支持一下！也欢迎在评论区分享你的使用体验和建议。