Activiti 手动部署 BPMN 文件时，仅生成 ge_bytearray 记录而未创建有效流程定义（re_procdef），通常因重复部署名称导致部署被跳过或覆盖。本文详解如何通过唯一部署名、规范 API 调用及资源加载方式，确保手动部署成功生成可用流程定义。
activiti 手动部署 bpmn 文件时，仅生成 `ge_bytearray` 记录而未创建有效流程定义（`re_procdef`），通常因重复部署名称导致部署被跳过或覆盖。本文详解如何通过唯一部署名、规范 api 调用及资源加载方式，确保手动部署成功生成可用流程定义。
在 Spring Boot + Activiti 环境中，启用自动部署（如 spring.activiti.check-process-definitions=true）时，框架会扫描 classpath:/processes/ 下的 .bpmn20.xml 文件并自动创建部署与流程定义。但切换为手动部署后，若未遵循 Activiti 的部署语义，极易出现“部署静默失败”——即 DeploymentBuilder.deploy() 返回了 Deployment 对象，数据库中仅写入 ge_bytearray（原始 XML 字节），却无对应的 re_procdef 记录，导致后续无法启动流程实例。
根本原因在于：Activiti 默认对同名部署进行去重处理。若多次执行相同 deploymentName 的部署（例如未显式指定名称，或始终使用默认空名），Activiti 会认为该部署已存在，跳过实际解析与流程定义注册，仅更新/复用字节数组。这正是你观察到 ge_bytearray 存在而 re_procdef 缺失的核心原因。
✅ 正确做法是：为每次部署指定唯一、可追溯的名称。推荐结合时间戳与业务标识，例如：
String deploymentName = String.format("process-deployment-%s",
new SimpleDateFormat("yyyyMMdd-HHmmss").format(new Date()));
DeploymentBuilder builder = repositoryService.createDeployment()
.name(deploymentName) // ← 关键：必须显式设置唯一部署名！
.category("custom-processes");同时，需注意以下关键实践：
-
避免混合使用
addBpmnModel()与addInputStream()：addBpmnModel()用于已解析的BpmnModel对象，但 Activiti 5/6 中更推荐直接添加原始 XML 流（更稳定、兼容性更好）。建议改用：InputStream input = resourceLoader.getResource(resource).getInputStream(); builder.addInputStream(processDefFile, input); // 直接传入文件名+流，无需手动解析
这样 Activiti 内部会完成解析、校验与部署，且能正确关联资源名与流程定义 ID。
-
确保资源路径可访问：
resourceLoader.getResource("classpath:/processes/")在打包为 JAR 后可能无法调用.getFile()（因资源位于 jar 包内）。应改用getURL()或更健壮的类路径扫描方式：Resource[] resources = resourceLoader.getResources("classpath:/processes/*.bpmn20.xml"); for (Resource resource : resources) { try (InputStream is = resource.getInputStream()) { String fileName = resource.getFilename(); String processDefKey = fileName.substring(0, fileName.indexOf(".bpmn20.xml")); builder.addInputStream(fileName, is); } } -
部署后验证：部署完成后，可通过以下代码确认流程定义是否就绪：
List<ProcessDefinition> defs = repositoryService.createProcessDefinitionQuery() .deploymentId(deployment.getId()) .list(); log.info("Deployed {} process definitions: {}", defs.size(), defs.stream().map(d -> d.getKey() + ":" + d.getVersion()).collect(Collectors.joining(", ")));
⚠️ 补充提醒：
- 若曾因错误部署产生脏数据，可临时清空
ACT_RE_DEPLOYMENT和ACT_RE_PROCDEF表（开发环境），或使用repositoryService.deleteDeployment(deploymentId, true)安全清理； - 生产环境务必禁用
spring.activiti.database-schema-update=true，改用 Liquibase/Flyway 管理 schema； - 永远不要在循环中反复调用
builder.deploy()—— 它应在所有资源添加完毕后调用一次。
遵循以上规范，即可确保手动部署生成完整的部署记录与可用流程定义，彻底解决“有 bytearray 无 procdef”的问题。
