HFS插件开发入门：从零开始创建自定义功能

HFS插件开发入门：从零开始创建自定义功能

【免费下载链接】hfsHFS is a web file server to run on your computer. Share folders or even a single file thanks to the virtual file system.项目地址: https://gitcode.com/gh_mirrors/hf/hfs

HFS（HTTP File Server）是一个强大灵活的Web文件服务器，通过插件系统可以轻松扩展功能。本文将详细介绍如何从零开始开发HFS插件，让你能够为这个文件服务器添加自定义功能。

🚀 为什么需要HFS插件开发？

HFS本身已经提供了完整的文件共享功能，但每个用户的需求各不相同。通过插件开发，你可以：

• 增强安全性- 添加暴力破解防护、IP限制等
• 丰富用户体验- 自定义界面主题、添加文件统计功能
• 扩展功能- 集成第三方服务、添加文件处理流程
• 自动化操作- 实现文件监控、自动备份等

HFS插件开发简单直接，无需复杂的环境配置，即可快速创建功能强大的扩展。

📁 插件基本结构

HFS插件是一个包含plugin.js文件的文件夹。要安装插件，只需将文件夹复制到plugins目录中。你可以在以下位置找到plugins文件夹：

• Windows：hfs.exe所在目录的plugins文件夹
• Linux/macOS：USER_FOLDER/.hfs/plugins目录

上图展示了HFS的典型目录结构，其中plugins文件夹就是存放插件的位置。

🔧 创建你的第一个插件

1. 基础插件模板

创建一个新的插件文件夹，例如my-first-plugin，在其中创建plugin.js文件：

exports.description = "我的第一个HFS插件" exports.version = 1.0 exports.apiRequired = 9.6 exports.init = function(api) { api.log("我的插件已加载！") return { unload: function() { api.log("我的插件已卸载！") } } }

2. 添加前端支持

插件可以包含前端（浏览器端）和后端（服务器端）代码。前端文件放在public文件夹中：

my-first-plugin/ ├── plugin.js # 主插件文件 ├── public/ │ ├── main.js # 前端JavaScript │ └── style.css # 前端样式 └── icons/ # 可选：自定义图标

在plugin.js中指定前端资源：

exports.init = function(api) { return { frontend_js: 'main.js', frontend_css: 'style.css' } }

🎯 插件配置系统

HFS提供了强大的配置系统，让管理员可以自定义插件行为：

exports.config = { message: { type: 'string', defaultValue: '欢迎使用我的插件', label: '欢迎消息', helperText: '用户登录时显示的消息' }, showCount: { type: 'boolean', defaultValue: true, label: '显示计数器' }, maxDownloads: { type: 'number', min: 1, max: 1000, defaultValue: 100, label: '最大下载次数' } }

配置值可以通过api.getConfig('message')在后台获取，或通过HFS.getPluginConfig('message')在前端获取。

🔌 事件系统：插件与HFS的桥梁

HFS提供了丰富的事件系统，让插件能够响应各种操作：

后端事件示例

exports.init = function(api) { api.events.on('login', function({ ctx }) { api.log(`用户 ${ctx.state.account?.username} 登录了`) }) api.events.on('deleting', function({ node }) { if (node.source.endsWith('.important')) { api.log("尝试删除重要文件，已阻止") return api.events.stop // 阻止删除操作 } }) }

前端事件示例

// 在public/main.js中 HFS.onEvent('afterEntryName', function({ entry }) { if (entry.hits) { return `<span style="color: green; margin-left: 8px">📥 ${entry.hits}</span>` } })

📊 实用插件示例：下载计数器

让我们看一个实际的插件示例 - 下载计数器插件，位于plugins/download-counter/plugin.js：

这个插件统计每个文件的下载次数，并在文件列表或右键菜单中显示。它展示了如何：

1. 使用数据库存储数据（通过api.openDb）
2. 通过中间件拦截下载请求
3. 修改目录条目显示信息
4. 提供用户可配置选项

exports.description = "统计每个文件的下载次数，并在列表或文件菜单中显示" exports.version = 6.4 exports.apiRequired = 8.89 exports.config = { where: { frontend: true, label: "显示位置", type: 'select', defaultValue: 'menu', options: ['list', { value: 'menu', label: "文件菜单" }] }, archives: { defaultValue: true, type: 'boolean', label: "统计压缩包内文件" } }

🛠️ 开发工作流程

热重载开发

HFS支持插件热重载，这意味着你可以在服务器运行时修改插件代码：

1. 在.hfs/plugins文件夹内创建插件目录
2. 编辑plugin.js文件
3. 保存后，HFS会自动重新加载插件
4. 立即看到效果，无需重启服务器

高级开发模式

对于更专业的开发，建议：

1. 在GitHub仓库中维护插件代码
2. 使用符号链接将dist文件夹连接到.hfs/plugins目录
3. 这样可以在编辑源代码的同时实时测试效果

# Linux/macOS ln -s /PATH_TO_YOUR_REPO/dist MY_PLUGIN_NAME # Windows mklink /d C:\path\to\hfs\plugins\my_plugin C:\my_code\my_plugin\dist

🌐 发布你的插件

GitHub发布指南

要让插件出现在HFS管理面板的插件列表中：

1. 在GitHub上创建仓库
2. 添加主题标签hfs-plugin
3. 确保插件文件位于dist文件夹中
4. 正确设置exports.apiRequired版本号
5. 填写详细的exports.description

多版本支持

如果你的插件需要支持不同版本的HFS：

1. 创建以api开头的分支（如api12.8）
2. 在不同分支中维护兼容不同API版本的代码
3. HFS会自动选择兼容的版本

💡 最佳实践

1. 错误处理

exports.init = function(api) { try { // 插件初始化代码 return { unload: cleanup } } catch (error) { api.setError(`插件初始化失败: ${error.message}`) return { unload: () => {} } } }

2. 资源管理

exports.init = function(api) { const intervals = [] // 定期执行任务 intervals.push(api.setInterval(() => { api.log("定期任务执行中...") }, 60000)) return { unload: () => { intervals.forEach(clearInterval) } } }

3. 国际化支持

// 前端国际化 const { t } = HFS const message = t('myPlugin_welcome', "欢迎使用我的插件") // 后端国际化 exports.init = async function(api) { const { t } = await api.i18n(ctx) const message = t('myPlugin_welcome', "欢迎使用我的插件") }

🚨 常见问题解决

插件不加载？

1. 检查plugin.js文件是否存在且语法正确
2. 确认exports.apiRequired设置正确
3. 查看HFS日志获取详细错误信息

配置不生效？

1. 确保在管理面板中保存了配置
2. 使用api.getConfig()正确读取配置
3. 配置字段名称与定义一致

前端代码不执行？

1. 确认frontend_js路径正确
2. 检查浏览器控制台是否有JavaScript错误
3. 确保文件在public文件夹中

📚 深入学习资源

要深入了解HFS插件开发，建议查看：

• 官方文档：dev-plugins.md - 完整的插件开发指南
• 示例插件：plugins/ - 查看现有插件实现
• API参考：src/ - 核心源代码

🎉 开始你的插件开发之旅

HFS插件系统为开发者提供了强大的扩展能力。无论你是想添加简单的界面调整，还是实现复杂的文件处理逻辑，插件开发都能满足你的需求。

记住这些关键点：

1. 插件是包含plugin.js的文件夹
2. 支持热重载，开发体验流畅
3. 提供丰富的事件和API接口
4. 配置系统让用户自定义行为
5. 前后端分离设计灵活

现在就开始创建你的第一个HFS插件，为这个优秀的文件服务器添加独特的功能吧！

【免费下载链接】hfsHFS is a web file server to run on your computer. Share folders or even a single file thanks to the virtual file system.项目地址: https://gitcode.com/gh_mirrors/hf/hfs