Directus项目中TUS_ENABLED配置导致媒体上传失败的解决方案

在Directus v11.2.1版本中，当启用TUS_ENABLED=true配置时，管理员控制台的媒体文件上传功能会出现异常。本文将详细分析该问题的成因，并提供有效的解决方案。

问题现象

当在Directus项目中设置TUS_ENABLED=true后，尝试通过管理员控制台上传媒体文件时，系统会抛出以下错误：

tus: unexpected response while uploading chunk

错误详情显示PATCH请求的URL路径中包含了多余的斜杠，导致404路由未找到的错误响应。具体表现为请求URL变成了"http://localhost:8055//files/tus/..."，其中包含了双斜杠"//"。

问题根源

经过分析，这个问题是由于PUBLIC_URL环境变量的配置不当引起的。当PUBLIC_URL的值以斜杠结尾时（如"http://localhost:8055/"），在与TUS上传组件的路径拼接过程中会产生多余斜杠，导致最终的请求URL格式不正确。

解决方案

要解决这个问题，只需对PUBLIC_URL环境变量进行简单调整：

1. 修改前（错误配置）：

PUBLIC_URL="http://localhost:8055/"

2. 修改后（正确配置）：

PUBLIC_URL="http://localhost:8055"

即移除PUBLIC_URL末尾的斜杠字符。这样修改后，TUS上传组件生成的请求URL将保持正确的格式，媒体文件上传功能即可恢复正常。

技术原理

TUS是一种基于HTTP的可恢复文件上传协议，Directus通过集成TUS实现了大文件分块上传和断点续传功能。当启用TUS_ENABLED时，系统会使用特定的URL路径进行文件上传操作。

URL路径的生成遵循以下规则：

PUBLIC_URL + "/files/tus/" + 文件ID

当PUBLIC_URL以斜杠结尾时，与后续路径拼接会产生双斜杠，导致路由匹配失败。这是Web服务器路由处理的常见问题，大多数Web框架会将双斜杠视为无效路径。

最佳实践

为避免类似问题，建议在配置Directus环境变量时注意以下几点：

1. PUBLIC_URL不应以斜杠结尾
2. 确保所有环境变量值的格式符合预期
3. 在修改配置后，重启Directus服务使更改生效
4. 对于生产环境，建议在修改前进行充分测试

通过遵循这些简单的配置规则，可以确保Directus的媒体上传功能在各种环境下都能稳定工作。