Ferdium自定义服务配方开发指南：解决服务消失问题

问题现象分析

在Ferdium 7.0.1版本中，部分Windows 11用户尝试创建自定义服务配方时遇到了一个典型问题：当直接将配方文件放置在/dev目录下时，会导致已配置的所有服务突然消失。这个现象实际上是由于文件路径结构不规范引起的系统识别异常。

根本原因

Ferdium的配方管理系统对自定义配方的目录结构有严格要求：

1. 每个配方必须位于独立的子目录中
2. 子目录名称需要保持唯一性
3. 正确的存放路径应为：
   • 推荐路径：<Ferdium配置目录>/recipes/dev/<自定义配方名称>
   • 备选路径：<Ferdium配置目录>/recipes/<自定义配方名称>

直接将配方文件放在/dev根目录会导致Ferdium无法正确解析配方结构，进而引发服务列表读取异常。

解决方案详解

正确创建自定义配方的步骤

1. 定位配置目录：

   • Windows系统通常位于%APPDATA%/Ferdium
   • 可通过Ferdium界面"添加服务→自定义配方→打开文件夹"快速定位

2. 创建规范目录结构：

   /recipes
   └── /dev
       └── /your_recipe_name
           ├── package.json
           ├── webview.js
           └── icon.svg
   

3. 配方文件要求：

   • package.json：必须包含有效的配方元数据
   • webview.js：定义服务的前端行为
   • 图标文件：推荐使用SVG格式

4. 重启生效：

   • 完成文件放置后需要重启Ferdium客户端

开发建议

1. 优先使用dev子目录：

   • 将自定义配方放在/dev下可以明确区分官方配方和本地配方
   • 避免与未来官方更新产生冲突

2. 版本控制方案：

   • 对于修改官方配方的需求，建议：
     • 复制原始配方到/dev下新目录
     • 修改副本而非原始文件
     • 通过Git等工具管理自定义配方

3. 调试技巧：

   • 使用开发者工具(CTRL+SHIFT+I)查看控制台日志
   • 检查配方加载时的网络请求

高级应用场景

企业级部署方案

对于需要团队共享配方的场景，可以考虑：

1. 建立内部配方仓库
2. 使用符号链接统一管理配方目录
3. 开发自动同步脚本

配方开发最佳实践

1. 保持与官方配方相同的文件结构
2. 在package.json中明确标注自定义标识
3. 定期与上游配方同步更新

通过遵循这些规范，用户可以安全地扩展Ferdium的功能而不会影响现有服务配置。对于高级用户，还可以探索通过插件系统实现更复杂的定制需求。