如何在PlantUML甘特图中通过!include引入自定义函数外部文件？

我在用PlantUML制作甘特图时，需要将任意日期转换为epoch_time，但PlantUML无内置该功能，因此编写了自定义转换函数。将函数直接写入@startgantt块内可正常运行，但尝试用!include从多个.pu文件引用时遇到问题：使用本地文件路径引入会报错；使用Gist的原始URL引入时，图表生成中断，!dump_memory命令无法执行。示例脚本如下：

@startuml test
' !include to_epoch_time.pu

[%filename() - 2 ]
[%file_exists("https://gist.githubusercontent.com/topchul/e635a3003ab1387d2fc9d92a09dc0249/raw/9a0cb98438d43c8099e0c1f2266b864eadbe2a17/to_epoch_time.pu") - exists 1]
[%file_exists("https://gist.githubusercontent.com/topchul/e635a3003ab1387d2fc9d92a09dc0249/raw/9a0cb98438d43c8099e0c1f2266b864eadbe2a17/to_epoch_time_1.pu") - exists 2]

' !include https://gist.githubusercontent.com/topchul/e635a3003ab1387d2fc9d92a09dc0249/raw/9a0cb98438d43c8099e0c1f2266b864eadbe2a17/to_epoch_time.pu
' !include https://gist.githubusercontent.com/topchul/e635a3003ab1387d2fc9d92a09dc0249/raw/9a0cb98438d43c8099e0c1f2266b864eadbe2a17/to_epoch_time_1.pu
!dump_memory
[$to_epoch_time("2024-01-01")]
@enduml

问题解答 #

1. PlantUML正确使用!include的示例 #

本地文件引入

根据文件位置选择对应路径：

• 同目录下的文件：直接引用文件名
• 子目录文件：使用相对路径
• 绝对路径：适用于固定位置的通用工具文件

@startuml
!include to_epoch_time.pu  ' 同目录文件
!include ./utils/date_converters.pu  ' 子目录相对路径
!include C:/PlantUML/utils/common_functions.pu  ' Windows绝对路径
!include /home/user/PlantUML/utils/date_utils.pu  ' Linux/macOS绝对路径
[$to_epoch_time("2024-01-01")]
@enduml

远程文件引入

使用文件的原始访问URL（确保链接可直接打开并返回纯文本内容）：

@startuml
!include https://raw.githubusercontent.com/xxx/xxx/main/to_epoch_time.pu
[$to_epoch_time("2024-01-01")]
@enduml

2. 跨多个.pu文件复用自定义函数的可行方案 #

• 集中管理：将所有自定义函数归类到单独的目录（如utils/），比如创建date_functions.pu、common_utils.pu等文件，统一维护和引用。
• 分层引入：如果函数存在依赖关系，先引入基础依赖文件，再引入上层函数文件，避免因依赖缺失报错。
• 避免重复引入：使用!include_once替代!include，防止同一文件被多次引入导致函数重复定义错误。
• 本地缓存远程函数：将远程函数文件下载到本地目录后再引用，避免网络波动、访问限制等问题，同时提升加载效率。

3. 当前引入失败问题的解决方法 #

本地文件引入报错排查

• 验证路径正确性：用[%filename() - 2 ]查看PlantUML当前工作目录，对比本地文件的实际存储路径，确保相对路径是相对于该工作目录的（而非当前.pu文件所在目录）。
• 检查文件权限：确保PlantUML进程有权限读取目标文件，Linux/macOS下可通过chmod +r filename.pu添加读权限。

远程URL引入中断排查

• 确认URL有效性：直接在浏览器打开Gist的原始URL，检查是否能正常显示函数代码（Gist的原始链接可能随版本更新变化，需复制最新的原始链接）。
• 排查网络问题：内网环境下需配置PlantUML代理，通过!set proxy=host:port设置代理服务器。
• 验证函数兼容性：确认自定义函数的语法与当前使用的PlantUML版本兼容，部分旧版本可能不支持复杂的自定义函数逻辑。
• 分步调试：先注释!dump_memory命令，单独测试!include和函数调用是否正常；用[%file_exists("远程URL")]检查PlantUML是否能访问到远程文件，逐步定位问题。

内容的提问来源于stack exchange，提问作者TopChul