tickstep/aliyunpan 插件开发完全指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00889/article/details/148523930

tickstep/aliyunpan 插件开发完全指南

aliyunpan 阿里云盘命令行客户端，支持JavaScript插件，支持同步备份功能。项目地址: https://gitcode.com/gh_mirrors/ali/aliyunpan

前言

tickstep/aliyunpan 是一款功能强大的阿里云盘命令行客户端，其插件系统为用户提供了高度自定义的能力。本文将全面解析该项目的插件机制，帮助开发者充分利用插件功能实现个性化需求。

插件系统概述

tickstep/aliyunpan 的插件系统基于 JavaScript 实现，允许用户在文件传输的关键环节注入自定义逻辑。插件主要覆盖以下场景：

上传/下载前的预处理
上传/下载完成后的后处理
同步过程中的过滤与转换
Token 刷新状态监控

插件配置与使用

插件文件结构

插件文件存放在程序所在目录的 plugin/js 子目录下，包含五种类型：

download_handler.js - 下载处理器
upload_handler.js - 上传处理器
remove_handler.js - 删除处理器
sync_handler.js - 同步处理器
token_handler.js - Token 处理器

使用前需将 .sample 后缀的示例文件重命名为 .js 后缀。

环境配置

如果通过环境变量 ALIYUNPAN_CONFIG_DIR 设置了配置目录，需要将 plugin 文件夹复制到配置目录中才能生效。

核心 API 详解

日志输出

console.log(): 调试日志，需开启 debug 模式可见
console.println(): 直接输出到控制台

HTTP 请求

PluginUtil.Http.get(): 发起 GET 请求
PluginUtil.Http.post(): 发起 POST 请求

示例：

var header = {
    "User-Agent": "Mozilla/5.0...",
    "Content-Type": "application/json"
};
var response = PluginUtil.Http.get(header, "https://api.example.com/data");

文件操作

PluginUtil.LocalFS.deleteFile(): 删除本地文件
PluginUtil.PanFS.deleteFile(): 删除云盘文件

邮件通知

PluginUtil.Email.sendTextMail(): 发送纯文本邮件
PluginUtil.Email.sendHtmlMail(): 发送 HTML 邮件

数据存储

PluginUtil.KV.putString(): 存储键值对
PluginUtil.KV.getString(): 获取键值

加密工具

PluginUtil.HashTool.md5Hex(): 计算字符串 MD5 值

典型应用场景

文件过滤

// 禁止特定类型文件上传
function uploadFilePrepareCallback(context, params) {
    var result = { "uploadApproved": "yes" };
    
    // 禁止 .txt 文件
    if (params["localFileName"].endsWith(".txt")) {
        result["uploadApproved"] = "no";
    }
    
    return result;
}

文件重命名

// 下载时截断过长文件名
function downloadFilePrepareCallback(context, params) {
    var result = { "downloadApproved": "yes" };
    
    // 仅保留文件名前10个字符
    var newName = params["driveFileName"].substring(0, 10);
    result["localFilePath"] = params["localFilePath"].replace(
        params["driveFileName"], 
        newName
    );
    
    return result;
}

自动化清理

// 上传完成后删除本地文件
function uploadFileFinishCallback(context, params) {
    if (params["uploadResult"] == "success") {
        PluginUtil.LocalFS.deleteFile(params["localFilePath"]);
    }
}

状态监控

// Token 刷新失败通知
function userTokenRefreshFinishCallback(context, params) {
    if (params["result"] === "fail") {
        PluginUtil.Email.sendTextMail(
            "smtp.example.com:465",
            "sender@example.com",
            "password",
            "receiver@example.com",
            "Token 刷新失败",
            params["message"]
        );
    }
}

高级技巧

限流控制

// 限制每次下载文件数量
function downloadFilePrepareCallback(context, params) {
    const MAX_COUNT = 3;
    var count = parseInt(PluginUtil.KV.getString("download_count") || 0;
    
    if (count >= MAX_COUNT) {
        return { "downloadApproved": "no" };
    }
    
    PluginUtil.KV.putString("download_count", count + 1);
    return { "downloadApproved": "yes" };
}

路径处理

// 规范化路径处理
function processPath(rawPath) {
    return rawPath
        .replace(/\\/g, "/")
        .replace(/\/+/g, "/")
        .replace(/\/$/, "");
}