115pan-node

一个用于 115 网盘的 Node.js/Bun SDK，支持二维码登录、文件管理、下载链接获取等功能。

A Node.js/Bun SDK for 115 Cloud Drive (115网盘), featuring QR code login, file management, download URL retrieval, and more.

特性

• 🔐 二维码登录 - 支持扫码登录，自动保存 cookies
• 📁 文件系统操作 - 列目录、搜索、创建文件夹、移动/复制/删除文件
• ⬇️ 下载链接获取 - 获取文件的下载直链
• 📤 上传支持 - 支持文件上传
• 🔗 离线下载/分享 - 离线任务与分享链接管理
• 🍪 Cookie 管理 - 自动持久化 cookies，支持自动重登录

安装

# Using bun (recommended)
bun add 115pan-node

# Using npm
npm install 115pan-node

# Using yarn
yarn add 115pan-node

# Using pnpm
pnpm add 115pan-node

快速开始

创建客户端

import { P115Client } from "115pan-node";

// 方式 1: 从 cookies 字符串创建
const client = new P115Client("UID=xxx; CID=xxx; SEID=xxx");

// 方式 2: 从 cookies 文件创建（推荐）
const client = await P115Client.fromPath("./115-cookies.txt");

// 方式 3: 空客户端，稍后登录
const client = new P115Client();

二维码登录

import { P115Client } from "115pan-node";
import qrcodeTerminal from "qrcode-terminal";

const client = new P115Client(undefined, {
  cookiesPath: "./115-cookies.txt", // 自动保存 cookies
});

await client.loginWithQrcode(
  "web",
  (qrcodeUrl, uid) => {
    // 在终端打印 ASCII 二维码
    qrcodeTerminal.generate(qrcodeUrl, { small: true }, console.log);
    console.log(`请用 115 App 扫码登录 (UID: ${uid})`);
  },
  (status) => {
    // status: 0=等待扫码, 1=已扫描待确认, 2=登录成功
    console.log("状态:", status);
  }
);

console.log("登录成功！用户 ID:", client.userId);

文件操作

// 列出目录
const result = await client.fsFiles({ cid: 0, limit: 50 });
console.log("文件列表:", result.data);

// 搜索文件
const search = await client.fsSearch({ search_value: "关键词", cid: 0 });

// 创建文件夹
await client.fsMkdir({ cid: 0, file_name: "新建文件夹" });

// 移动文件
await client.fsMove({ fid: "文件ID", pid: "目标目录ID" });

// 复制文件
await client.fsCopy({ fid: "文件ID", pid: "目标目录ID" });

// 删除文件/文件夹
await client.fsDelete({ fid: "文件ID" });

获取下载链接

// 获取文件下载链接
const download = await client.downloadUrlWeb({ pickcode: "文件提取码" });
console.log("下载地址:", download.file_url);

// 批量获取
const batch = await client.downloadUrlApp({ pickcode: "code1,code2,code3" });

分享链接

// 获取分享链接信息
const info = await client.shareInfo({ share_code: "分享码" });

// 保存分享文件到网盘
await client.shareReceive({
  share_code: "分享码",
  receive_code: "提取码",
  fid: "文件ID",
  cid: "目标目录ID"
});

API 参考

P115Client

主客户端类，提供所有 API 方法。

构造函数

new P115Client(cookies?, options?)

• cookies: 可选，cookies 字符串或对象
• options:
  • cookiesPath: cookies 文件路径，自动读写
  • checkForRelogin: 是否在收到 405 响应时自动重新登录

静态方法

P115Client.fromPath(path, options?): Promise<P115Client>

从文件读取 cookies 并创建客户端实例。

文件系统方法

| 方法 | 说明 | |------|------| | fsFiles({ cid, limit, offset, ... }) | 列出目录内容 | | fsSearch({ search_value, cid, ... }) | 搜索文件 | | fsMkdir({ cid, file_name }) | 创建文件夹 | | fsMove({ fid, pid }) | 移动文件 | | fsCopy({ fid, pid }) | 复制文件 | | fsDelete({ fid }) | 删除文件 | | fsRename({ fid, file_name }) | 重命名 | | fsInfo({ fid }) | 获取文件信息 | | fsGetPath({ fid }) | 获取文件路径 |

下载方法

| 方法 | 说明 | |------|------| | downloadUrlWeb({ pickcode }) | 获取下载链接（Web 接口） | | downloadUrlApp({ pickcode }) | 获取下载链接（App 接口） | | downloadFolders({ pickcode }) | 获取下载文件夹列表 | | downloadFiles({ pickcode }) | 获取下载文件列表 |

登录方法

| 方法 | 说明 | |------|------| | loginQrcodeToken(app) | 获取二维码 token | | loginQrcodeScanStatus({ uid, time, sign }) | 查询扫码状态 | | loginQrcodeScanResult(uid, app) | 获取登录结果 | | loginWithQrcode(app, onQrcode, onStatus) | 完整扫码登录流程 |

分享方法

| 方法 | 说明 | |------|------| | shareInfo({ share_code }) | 获取分享信息 | | shareReceive({ share_code, receive_code, ... }) | 保存分享文件 | | offlineTaskAdd({ url }) | 添加离线任务 |

运行演示

# 克隆项目
git clone https://github.com/yourusername/115pan-node.git
cd 115pan-node

# 安装依赖
bun install

# 运行演示（扫码登录）
bun run demo

# 使用保存的 cookies
bun run demo:save

开发

# 运行测试
bun test

# 构建产物
bun build ./index.ts --outdir ./dist

类型导出

// 主要类型
export type { P115ClientOptions, RequestOptions };
export type { P115CookiesData, DirNode, P115URL };

// 错误类
export {
  P115OSError,
  P115AuthenticationError,
  P115BusyOSError,
  P115DataError,
  P115OperationalError,
  P115AccessError,
  P115FileTooBig,
  P115ExceededError,
  P115InvalidArgumentError,
  P115NoSpaceError,
  P115NotSupportedError,
  P115LoginError,
};

注意事项

• 本项目为非官方 SDK，仅供学习研究使用
• 请合理使用 API，避免频繁请求
• Cookies 包含敏感信息，请妥善保管

License

MIT

贡献

欢迎提交 Issue 和 Pull Request！