FilePond 初始化未显示拖拽区域，主因是未引入官方CSS样式表或目标DOM元素未就绪；必须显式加载filepond.min.css，并确保初始化代码在DOMContentLoaded后执行，且绑定真实、已挂载的空input节点。
FilePond 初始化时为什么没显示拖拽区域？
常见原因是 DOM 元素未就绪或缺少基础样式。FilePond 不会自动注入 CSS，必须显式引入官方样式表，否则 filepond 容器渲染为空白或仅显示原生 input。
- 确保在
<head>中加载filepond/dist/filepond.min.css - 初始化前确认目标元素已存在于 DOM：不要在
document.querySelector之前执行脚本，或用DOMContentLoaded包裹 - 目标元素需是空的
<input type="file">，且带id或 class，例如：<input type="file" id="filepond-input"> - 若用框架（如 Vue/React），注意生命周期 —— 原生初始化必须等真实 DOM 节点挂载完成
如何启用图片预览并限制只传图片？
FilePond 默认不开启预览，需手动启用插件并配置类型校验。图片预览依赖 FilePondPluginImagePreview，且必须配合 allowImagePreview 和 imagePreviewHeight 等参数生效。
- 引入插件 JS：
filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.js - 调用
FilePond.registerPlugin(FilePondPluginImagePreview)注册插件 - 初始化时设置：
allowImagePreview: true、allowMultiple: false（按需）、maxFiles: 1 - 限制类型：用
acceptedFileTypes: ['image/jpeg', 'image/png', 'image/gif']，比后缀名更可靠；后缀过滤（如.jpg）容易被绕过 - 注意：预览图宽高由
imagePreviewHeight和styleLoadIndicator等控制，不设可能导致缩略图挤压变形
上传失败时 console 显示 413 Payload Too Large 怎么办？
这是服务端拒绝大文件，FilePond 本身不限制大小，但默认配置不会主动截断或提示用户。必须前后端协同处理。
- 前端加限制：
maxFileSize: '2MB'（字符串格式），超出会触发filevalidateerror事件 - 监听该事件可自定义提示：
onfilevalidateerror: (file, error) => { alert('文件不能超过2MB') } - 后端 Nginx 需调大
client_max_body_size；PHP 要改upload_max_filesize和post_max_size - 注意：FilePond 的
server.process配置中若用了代理或自定义 fetch，需确保 headers 和 body 未被意外修改导致 size 计算异常
为什么拖拽文件后预览一闪而过就消失了？
大概率是 FilePond 将文件视为“已处理”，但没真正上传或没正确响应服务端返回。它默认要求服务端返回包含 id 字段的 JSON，否则认为上传失败并清理临时预览。
立即学习“前端免费学习笔记（深入）”；
- 服务端响应必须是
200 OK，且 body 为 JSON：{"success": true, "id": "abc123"}（id是必需字段） - 若用 mock 或本地测试，可用
server: { url: '/fake-upload', process: () => Promise.resolve({ id: 'tmp-' + Date.now() }) } - 检查浏览器 Network 面板：确认请求发出、响应状态码为 200、响应体可解析为 JSON
- 禁用自动移除：设
instantUpload: false可保留文件在列表中，便于调试流程
预览逻辑和上传生命周期耦合紧密，漏掉 id 或响应格式不对，FilePond 就会清掉预览——这点很容易忽略，尤其在快速对接 mock 接口时。
