自托管Appwrite调用createDocument/updateDocument报类型转换错误

你的核心问题是Nginx Proxy Manager返回的301重定向响应被Appwrite SDK当成JSON解析，导致出现type 'String' is not a subtype of type 'Map<String, dynamic>'错误。list/get接口能正常工作是因为它们用的是GET请求，Nginx对GET的重定向处理相对兼容，但create/update用的POST/PUT请求被异常重定向，返回了HTML页面而非预期的JSON响应。

解决步骤： #

1. 修正Flutter客户端的Appwrite端点配置
   初始化Client时必须使用对外的正确HTTPS地址（若开启了SSL），禁止用HTTP。示例代码：

   final client = Client()
       .setEndpoint('https://your-appwrite-domain/v1') // 替换为你的Appwrite域名
       .setProject('your-project-id')
       .setKey('your-api-key');
   

   若之前用HTTP，Nginx强制跳转到HTTPS会触发301，而SDK默认不会自动处理POST请求的重定向，直接接收了HTML响应导致解析错误。

2. 检查Nginx Proxy Manager的代理配置

   • 调整「Force SSL」选项：若开启了强制SSL，确认Nginx不会把POST请求转为GET（部分反向代理会对POST的301跳转做方法转换，导致Appwrite无法识别请求）。
   • 添加必要代理头：在「高级」配置中加入以下内容，确保Appwrite能正确识别请求的协议和来源：

     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto $scheme;
     

   • 移除无效重定向规则：检查是否设置了针对Appwrite域名的无条件301重定向，这类规则会干扰POST/PUT请求。

3. 验证Appwrite容器的环境变量
   确保Appwrite容器的_APPWRITE_ENDPOINT环境变量设置为对外的HTTPS域名，例如：

   _APPWRITE_ENDPOINT=https://your-appwrite-domain/v1
   

   该变量决定Appwrite返回的内部链接地址，错误配置会导致客户端跳转异常。

4. 直接测试API接口
   用curl绕过Nginx Proxy Manager，直接请求Appwrite服务的createDocument接口，验证服务本身是否正常：

   curl -X POST "http://appwrite-container-ip:80/v1/databases/{dbID}/collections/{collectionID}/documents/BDRec0000001" \
   -H "Content-Type: application/json" \
   -H "X-Appwrite-Project: {your-project-id}" \
   -H "X-Appwrite-Key: {your-api-key}" \
   -d '{"item":1,"itemMake":1,"sn":"GHTDD001Z001","permissions":["read(any)","update(any)"]}'
   

   若请求能正常返回JSON，说明问题完全在Nginx Proxy Manager的配置上；若仍报错，需检查集合权限、API密钥是否拥有documents.write权限。

补充说明 #

解决301重定向问题后，SDK就能接收到正确的JSON响应，type 'String' is not a subtype...的错误会自动消失。

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