使用Directus无头CMS上传文件后API返回文件字段为null，如何解决？

我之前在使用Directus做无头CMS的时候，也碰到过上传文件后API返回字段为null的问题，踩了几个坑才解决，给你分享几个排查和解决的方向：

1. 先检查权限配置，这是最容易忽略的点 #

• 确认你调用API所用的角色，是否拥有对应文件字段的读取权限。Directus的权限管控很细，哪怕你能成功上传文件，如果角色没有该字段的读取权限，API就会返回null。
• 操作路径：Directus后台 → 找到目标集合 → 点击「权限」标签 → 找到你的角色 → 检查文件字段的权限是否设为「允许读取」。

2. 确认文件字段的基础配置 #

• 先核实这个字段是不是标准的「文件」类型，别不小心建了文本或者其他类型的字段。
• 查看字段的关系设置，确保它关联的是Directus内置的files集合，没有选错关联目标或者配置错误。

3. 检查API请求的参数是否正确 #

• 如果用的是REST API：默认情况下Directus不会返回所有关联字段，你需要在请求里明确指定要返回的字段。比如请求URL要写成：

  GET /items/your-collection?fields=*,your_file_field.*
  

  这里的your_file_field.*是告诉API返回文件字段的完整信息，而不是只返回ID或者空值。
• 如果用的是GraphQL API：要确保查询语句里明确请求了文件字段的相关属性，比如：

  query {
    your_collection_item(id: 1) {
      id
      title
      your_file_field {
        id
        filename_disk
        url
      }
    }
  }
  

4. 排查文件存储驱动的问题 #

• 如果你配置了自定义存储（比如S3、腾讯云COS等），先确认存储配置是否正确，文件是否真的上传到了存储服务里。有时候表面上显示上传成功，但实际存储失败，就会导致API返回null。
• 可以临时切换回Directus默认的本地存储，测试一下是否能正常返回文件字段，排除存储驱动的问题。

5. 清除Directus缓存试试 #

• Directus会缓存配置和数据，有时候缓存异常会导致字段返回错误。你可以在后台「设置」→「缓存」里点击「清除所有缓存」，然后重新上传文件再调用API看看。

6. 检查Directus版本是否有bug #

• 某些旧版本的Directus存在文件字段返回null的已知bug，如果你用的版本比较老，建议升级到最新的稳定版，大概率能解决问题。

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