故障排查

建议始终先运行：

excelflow validate --plan extraction_plan.xlsx

validate 只检查计划文件的结构和声明关系，不读取源数据。因此它无法提前发现源 Sheet 缺失、源列缺失、表头不合法、类型转换失败或表达式引用的源列不存在；这些问题会在 run 读取源 Excel 后报告。

找不到 excelflow 命令

确认已经安装并且工具目录位于 PATH：

excelflow --help

使用项目虚拟环境开发时可运行 uv run excelflow --help。

提示缺少工作表

计划文件必须包含“抽取计划、数据对象、关联关系、字段映射、过滤条件”五张基础配置表。聚合使用的“分组字段”和“聚合规则”在新版模板中提供，但为了兼容旧计划，它们可以不存在。

提示源 Excel 中不存在工作表

“数据对象”的 Sheet名称必须与源数据文件中的标签完全一致。还要确认没有把计划文件误当成源数据文件传给 run。

提示表头不合法

检查“表头行”是否指向真正的列名行。列名必须唯一，并符合简单标识符规则：以英文字母或下划线开头，后续使用英文字母、数字、下划线或 $。推荐使用 snake_case，避免空格和中文列名。

这个错误来自源数据 Excel，只有执行 run 时才会检查。计划中的“表头行”从 1 开始计数。

任务无法执行

• “抽取计划”中的任务ID必须与命令一致；
• “启用”必须是“是”；
• 每个任务必须且只能有一个主表；
• 所有非主表对象都必须按顺序关联。

关联配置报错

左侧字段必须来自主表或先前已经关联的对象，右侧字段必须使用本次“右侧对象”的别名。同一关联顺序用于复合键时，关联类型和右侧对象必须一致。

结果行数变多

这通常是一对多关联造成的：主表的一行在右侧匹配多行，于是输出多行。检查关联字段在右侧是否唯一，以及复合键是否漏填。

结果行数变少

可能原因：

• 使用了 INNER JOIN，未匹配记录被删除；
• 过滤条件过严；
• 本应表示“或者”的条件被放进同一条件组。组内条件是 AND，不同组之间是 OR。

关联后的字段为空

LEFT JOIN 会保留主表记录，未匹配的右侧字段为空。检查关联值的类型、空格和复合键；如果业务允许默认值，可在表达式中使用 coalesce。

类型转换失败

目标类型为 integer、decimal 或 datetime 时，无法转换的文本会导致任务失败。先在源数据中清理异常值。string 会把非空值转换成文本。ExcelFlow 对数值和日期转换使用严格错误模式，不会静默忽略无法转换的非空值。

表达式失败

检查函数名、参数数量、字段名和数据类型。字符串、日期、条件及数值函数的完整签名见表达式参考。日期和数值转换采用严格模式；非法非空值会失败。表达式不支持自定义 Python、方法调用、目标字段或另一衍生列。validate 不解析表达式，因此这类错误通常在 run 时出现。

聚合结果不符合预期

• 聚合在关联和过滤之后执行；一对多关联可能放大行数和求和结果。
• count 只统计源字段非空值，count_all 统计组内所有行，业务对象计数通常使用 count_distinct。
• sum 的全空组返回空值，不返回 0。
• first、last 按当前输入行序，不代表日期最早或最晚。
• 聚合任务不能同时填写字段映射；聚合源字段也不能填写表达式。

LIKE 没有得到预期结果

% 表示任意长度字符，_ 表示任意一个字符，匹配整个字段。例如 ap% 匹配 apple。匹配会按字符串执行。

输出文件后缀和内容不一致

实际格式由命令中的 --format（-f）选项决定，不由 --output（-o）路径的后缀推断。建议保持两者一致。

输出为空

先复制计划文件用于排查，再在副本中暂时移除过滤条件确认关联结果，之后逐组恢复条件。也可在副本中将 INNER JOIN 暂改为 LEFT JOIN 来检查未匹配数据。修改后重新运行 validate，再执行 run 观察实际输出；preview 只展示声明，不读取源数据，也不会显示中间结果。