FilePond 初始化必须绑定已挂载DOM节点，预览需手动启用imagePreview并引入对应插件，上传需正确配置server.process对象；三者缺一将导致静默失效。
FilePond 初始化必须绑定真实 DOM 节点，不能只写 <input type="file"> 标签
FilePond 不会自动扫描页面上的 <input type="file"> 并接管它——你得显式调用 FilePond.create()，且传入一个已挂载的 DOM 元素。常见错误是 HTML 里写了 <input id="filepond">，但 JS 在 DOM 加载前就执行了初始化，导致返回 null 或静默失败。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 确保初始化代码在
DOMContentLoaded事件后执行，或把 script 放在 body 底部 - 用
document.getElementById('filepond')获取元素，不要依赖 querySelector 模糊匹配 - 若使用框架（如 Vue/React），需在组件 mounted / useEffect 中初始化，且确认 ref 已绑定到真实节点
预览功能依赖 filepond-plugin-image-preview，且需手动启用 imagePreview
FilePond 默认不开启图片预览，即使你引入了插件，也得在配置中显式打开 imagePreview 选项。否则拖进图片只会显示文件名和大小，没有缩略图。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 通过 CDN 引入时，顺序不能错：
filepond.js→filepond-plugin-image-preview.js→filepond-plugin-image-preview.css - 初始化时必须传入
{ imagePreview: true }，仅引入插件不生效 - 预览依赖浏览器原生
URL.createObjectURL()，所以上传大图（如 >10MB）可能卡顿或触发内存警告，生产环境建议加maxFileSize限制
拖拽区域样式失效？检查 allowDrop 和父容器宽高
FilePond 默认启用拖拽（allowDrop: true），但如果你看不到虚线边框或“Drop files here”提示，大概率是容器没尺寸——FilePond 的拖拽检测区域是基于父元素计算的，如果外层 <div> 高度为 0，就无法响应拖入事件。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 给 FilePond 容器（即传入
create()的那个元素的父级）设最小高度，例如min-height: 200px - 禁用默认拖拽只需配
{ allowDrop: false }，但一般不建议，除非业务明确不需要 - 自定义拖拽文案用
labelIdle，比如labelIdle: '拖拽文件到这里，或 <span class="filepond--label-action">浏览</span>'
上传前预览正常，但提交后后端收不到文件？检查 server.process 配置
FilePond 的预览和上传是两个阶段：预览走浏览器本地渲染，上传才发请求。很多人卡在“能看到缩略图，但点提交没网络请求”，根本原因是没配 server.process，或者路径写错、没处理 FormData。
实操建议：
立即学习“前端免费学习笔记（深入）”；
-
server.process必须是对象，含url字段（如{ url: '/api/upload' }），不能只写字符串 - 后端接口需接收
multipart/form-data，FilePond 默认字段名是file，可用server.process.method和server.process.headers调整 - 开发时打开浏览器 Network 面板，筛选 XHR，看是否有请求发出；若无，说明 FilePond 还没走到上传逻辑，优先查
allowMultiple、required等校验是否阻断了流程
