DocType 变更后字段不显示问题总结与解决方案
问题现象
- 在本地开发环境中,DocType 新增或修改字段(如
mark
字段)后,前端 desk 可以正常显示。 - 将代码(json 文件)推送到 Github 并在新环境部署后,虽然 json 文件中有新字段,但 desk 前端却无法看到。
- 即使执行了
bench migrate
,问题依旧。
原因分析
Frappe 的 DocType 定义有两份:
- 数据库中的 DocType 配置(
tabDocType
、tabDocField
等表) - apps 目录下的 json 文件(如
rg_production_orders.json
)
- 数据库中的 DocType 配置(
frappe 以数据库为准:
- 你在开发环境用 UI 改 DocType,frappe 会同步到数据库,并导出 json 文件。
- 你直接改 json 文件,数据库不会自动同步,frappe 只会用数据库里的定义。
bench migrate
不会自动用 json 覆盖数据库 DocType 配置:- 这样做是为了防止误删线上字段或数据。
- 所以 migrate 只做数据库 schema 迁移和 patch,不 reload DocType。
解决方案
1. 手动同步 DocType
每次部署后,必须执行 reload-doc,用 json 文件内容覆盖数据库 DocType 配置:
bench --site [site_name] reload-doc [app_name] doctype [DocType名称]
如:
bench --site site1.local reload-doc rongguan_erp doctype rg_production_orders
2. 批量 reload
如果有多个 DocType,可以批量 reload:
for dt in $(ls apps/erpnextcn/erpnextcn/erpnextcn/doctype/); do
bench --site site1.local reload-doc erpnextcn doctype $dt || true
done
for dt in $(ls apps/rongguan_erp/rongguan_erp/rongguan_erp/doctype/); do
bench --site site1.local reload-doc rongguan_erp doctype $dt || true
done
3. 自动化建议
在自动化部署脚本中,建议在所有 app 安装完毕后、关闭开发者模式前,统一 reload-doc。
示例插入位置:
bench --site ${siteName} install-app erpnextcn
bench --site ${siteName} install-app rongguan_erp
# reload erpnextcn 所有 DocType
for dt in $(ls /home/${userName}/${installDir}/apps/erpnextcn/erpnextcn/erpnextcn/doctype/); do
bench --site ${siteName} reload-doc erpnextcn doctype $dt || true
done
# reload rongguan_erp 所有 DocType
for dt in $(ls /home/${userName}/${installDir}/apps/rongguan_erp/rongguan_erp/rongguan_erp/doctype/); do
bench --site ${siteName} reload-doc rongguan_erp doctype $dt || true
done
bench --site ${siteName} set-config developer_mode 0
最佳实践
- 开发时:用 UI 改 DocType,改完后导出 json(
bench export-fixtures
或bench export-doc
)。 - 生产/部署时:只用 json 文件做版本管理,部署后自动 reload-doc。
- 不要直接手动改 json 文件然后指望 migrate 自动同步。
总结
- frappe 的 DocType 以数据库为准,json 只是导入导出用。
- 只要你直接改 json,就要 reload-doc。
- 建议开发用 UI 改,生产用 reload-doc 自动同步。