KeystoneJS 文件上传功能实现指南

在KeystoneJS项目中实现文件上传功能是许多开发者会遇到的需求。本文将详细介绍如何在KeystoneJS中通过GraphQL API实现文件上传功能，包括常见问题的解决方案和最佳实践。

文件上传的基本原理

KeystoneJS使用GraphQL的多部分请求规范来处理文件上传。这种机制允许客户端将文件作为多部分表单数据的一部分发送到服务器，同时保持GraphQL查询的结构化特性。

实现步骤

1. 配置KeystoneJS文件字段

首先需要在KeystoneJS模型中定义文件字段：

import { file } from '@keystone-6/core/fields';

export const VideoObject = {
  fields: {
    file: file({
      storage: 'my_local_storage',
    }),
  },
};

2. 客户端上传实现

使用Axios和FormData实现文件上传的客户端代码：

const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

async function uploadFile(filePath) {
  const fileStream = fs.createReadStream(filePath);
  const formData = new FormData();
  
  formData.append('operations', JSON.stringify({
    query: `
      mutation($file: Upload!) {
        createVideoObject(data: { file: { upload: $file } }) {
          file {
            filename
            filesize
          }
        }
      }
    `,
    variables: { file: null },
  }));

  formData.append('map', JSON.stringify({
    '0': ['variables.file'],
  }));

  formData.append('0', fileStream);

  const response = await axios.post(GRAPHQL_API_URL, formData, {
    headers: formData.getHeaders(),
  });
  
  return response.data;
}

关键注意事项

1. 文件字段结构：在GraphQL变量中，必须使用{ upload: $file }的结构，这是KeystoneJS处理文件上传的特定格式。

2. 多部分请求格式：请求必须包含三个部分：

   • operations：包含GraphQL查询和变量
   • map：定义文件与变量的映射关系
   • 实际文件内容

3. 大文件处理：对于视频等大文件，需要确保：

   • 服务器配置了足够大的请求体限制
   • 考虑使用流式上传或分块上传技术

常见问题解决

1. 返回null问题：如果响应中文件字段为null，通常是因为：

   • 文件字段结构不正确（缺少upload包装）
   • 文件映射关系定义错误

2. 请求大小限制：默认情况下，Node.js服务器对请求体大小有限制，需要适当调整：

   // 在Express/Next.js配置中
   app.use(express.json({ limit: '50mb' }));
   app.use(express.urlencoded({ limit: '50mb', extended: true }));
   

3. 存储配置：确保文件存储配置正确，KeystoneJS支持本地存储和云存储等多种选项。

高级用法

对于生产环境，建议考虑：

1. 文件验证：在resolveInput钩子中添加文件类型和大小验证
2. 进度跟踪：实现上传进度指示
3. 断点续传：对大文件实现分块上传
4. 安全考虑：限制上传文件类型，防止恶意文件上传

通过以上方法，开发者可以在KeystoneJS项目中实现可靠的文件上传功能，满足各种业务需求。