Frappe/ERPNext 自定义字段迁移指南

一、概述

自定义字段(Custom Field)是 Frappe/ERPNext 中一个重要的功能，允许我们在不修改原始 DocType 的情况下添加新的字段

二、创建自定义字段的方法

1. 通过 Web 界面创建
   路径: Setup → Customize → Custom Field
   优点：直观，可以立即看到效果
   缺点：无法版本控制，迁移时需要手动操作
2. 通过代码创建(推荐)

# custom_fields.py
def setup_custom_fields():
    custom_fields = {
        "Sales Order": [
            {
                "label": "Test Field 1",
                "fieldname": "test_custom_field1", 
                "fieldtype": "Data",
                "insert_after": "title",
                "translatable": 0
            }
        ]
    }
    
    create_custom_fields(custom_fields)

三、自定义字段配置说明

1. 必填参数

1. 可选参数

四、自定义字段的持久化

1. 配置 fixtures

# hooks.py
fixtures = [
    {
        "dt": "Custom Field",
        "filters": [
            ["dt", "in", ["Sales Order", "Work Order"]],
            ["fieldname", "in", ["test_custom_field1", "test_custom_field2"]]
        ]
    }
]

1. 配置安装钩子

# hooks.py
after_install = "testcustomfield.custom_fields.setup_custom_fields"

五、重要说明

1. 字段持久性
   自定义字段会保存在数据库的 tabCustom Field 表中
   卸载应用时默认不会删除这些字段
   升级 Frappe/ERPNext 不会影响自定义字段
2. 最佳实践
   使用统一的命名规范(如 custom_ 前缀)
   通过代码管理自定义字段
   使用 fixtures 确保配置可迁移
   保持字段命名的唯一性

六、常用操作

1. 导出自定义字段

bench --site your-site export-fixtures

1. 安装应用时创建字段

bench --site your-site install-app your-app

3. 检查字段是否存在

frappe.get_meta("Sales Order").get_field("test_custom_field1")

4. 手动删除字段

frappe.delete_doc("Custom Field", "Sales Order-test_custom_field1")

七、注意事项

1. 安全性
   添加字段前确认字段名不与现有字段冲突
   谨慎删除生产环境中的自定义字段
2. 性能
   避免添加过多不必要的自定义字段
   合理使用字段类型，避免过度使用复杂字段类型
3. 维护
   保持文档更新
   定期检查和清理未使用的自定义字段
   在测试环境验证后再部署到生产环境

八、故障排除

1. 字段未显示
   清除缓存：bench clear-cache
   重建前端资源：bench build
   重启服务：bench restart
2. 字段无法删除
   检查字段依赖关系
   确认字段未被其他文档引用
3. 迁移问题
   确保 fixtures 配置正确
   检查字段命名是否规范
   验证过滤器是否正确设置