故障排除
从第一个失败边界开始：注册、查询、转换、存储或交付。保留原始异常，因为它包含 Feed 类和输出上下文。
找不到 Feed 类
确认注册记录包含完整类名、Composer 自动加载能够解析该类，并且该类继承 DragonCode\LaravelFeed\Feeds\Feed 或预设。移动类后运行 composer dump-autoload。
生成占用过多内存
- 从
builder()返回 EloquentBuilder。 - 不要对完整数据集调用
get()、all()或toArray()。 - 降低
chunkSize()并重新测量。 - 使用
perFile()拆分大型输出。 - 只有 Feed 本身保持流式处理后，才将任务移到异步队列。
请参阅性能。
队列任务没有运行
检查 FEED_QUEUE_CONNECTION、FEED_QUEUE_NAME 和工作进程命令。sync 连接会立即运行，无法测试异步交付。唯一性锁可能阻止同一 Feed 的另一个任务，直到 FEED_QUEUE_UNIQUE_TTL 过期。
存储磁盘被拒绝
磁盘必须解析为 Illuminate\Filesystem\FilesystemAdapter，并支持可写流、移动、目录管理、列表和删除。无法解析为 FilesystemAdapter 的自定义实现会在数据库查询开始前抛出 UnsupportedStorageDiskException。Laravel 只读磁盘会通过该类型检查；写入会在 Feed 查询和本地暂存完成后的发布阶段失败，GeneratorService 会将该存储错误包装为 FeedGenerationException。
XML 生成失败
验证通过 @mixed 传入的原始 XML，确保 CDATA 内容有效，并让指令值符合文档规定的标量或数组契约。除非必须使用原始 XML，否则应使用普通转义值。
CSV 行在第一项之后失败
CSV 根据输出结构建立列。每个 Feed 项必须生成相同的键。可选值会保留空列，而不是将其删除。
已发布文件不完整或过期
检查原始存储异常并验证磁盘权限。对于远程磁盘，应考虑最终一致性以及非原子的复制后删除移动。如果多个主机上的生成器可能发布同一目标，则需要外部分布式锁。
发布期间，Laravel Feeds 会在目标路径旁创建临时 .feeds_staging_* 目录。发布成功后以及发生普通生成失败后，都会删除该目录。回滚失败时会保留该目录，以便其中的备份仍可使用。进程中断或清理失败也可能留下此类目录。
如果 .feeds_staging_* 目录数量很多或持续增加，说明发布或清理反复失败。检查生成日志和原始异常，修复底层的存储、权限或进程故障，并在手动删除遗留目录前检查所有保留的备份。