本文详解如何在 filepond 中正确预加载服务端已存在的文件（如用户历史附件），使其以“已上传”状态显示并可直接下载，避免重复上传或误判为待上传文件。
本文详解如何在 filepond 中正确预加载服务端已存在的文件（如用户历史附件），使其以“已上传”状态显示并可直接下载，避免重复上传或误判为待上传文件。
FilePond 默认将调用 addFiles() 添加的文件视为待上传的新文件，因此直接使用 pond.addFiles(files[j]) 会导致已存在的附件被错误标记为“未上传”，触发冗余上传请求。正确做法是：在初始化 FilePond 实例时，通过 files 属性声明初始文件列表，并显式标注其为 local 类型——这告诉 FilePond：“该文件已在服务端存在，仅需展示和管理，无需再次上传”。
✅ 正确初始化预加载文件
const pond = FilePond.create(document.querySelector('#filepond'), {
allowMultiple: true,
instantUpload: false,
server: {
url: BASE_URL,
timeout: 7000,
// 关键：配置 fetch 接口以支持文件下载（必需！）
fetch: (url, options) => {
return fetch(url, { ...options, cache: 'no-cache' });
},
load: (source, load, error, progress, abort) => {
// 实现文件下载逻辑（例如从 BASE_URL + source 获取文件流）
const myURL = `${BASE_URL}/download?file=${encodeURIComponent(source)}`;
const xhr = new XMLHttpRequest();
xhr.open('GET', myURL);
xhr.responseType = 'blob';
xhr.onload = function () {
if (xhr.status >= 200 && xhr.status < 300) {
load(xhr.response);
} else {
error('Failed to load file');
}
};
xhr.onerror = () => error('Network error');
xhr.send();
return () => xhr.abort();
}
},
// ? 核心：预设已上传文件列表
files: data.attachments_path.map(path => ({
source: path, // 文件唯一标识（如服务端路径或ID）
options: {
type: 'local', // 告知 FilePond：此文件已存在于服务端
}
}))
});⚠️ 关键注意事项
- source 必须唯一且稳定：建议使用服务端返回的文件 ID 或哈希路径（如 /uploads/report_v2.pdf），不可使用临时 URL 或含时效参数的链接；
- 必须配置 server.load 方法：FilePond 对 local 类型文件默认不提供下载能力，需手动实现 load 回调，用于点击“下载”按钮时拉取原始文件内容；
- 避免混用 addFiles() 初始化后添加：若需动态追加历史文件，请改用 pond.setOptions({ files: [...existing, ...newFiles] }) 重置整个列表，而非 addFiles()；
- 服务端需提供安全的下载接口：确保 BASE_URL/download?file=xxx 接口校验权限、防止路径遍历（如对 path 参数做白名单过滤或映射）。
? 补充：启用下载按钮（UI 友好）
FilePond 默认为 local 文件显示下载图标，但需确保启用了相关插件（推荐引入 filepond-plugin-file-encode 和 filepond-plugin-file-validate-type 以增强体验）。若未显示下载按钮，可在初始化中显式启用：
FilePond.registerPlugin(
FilePondPluginFileEncode,
FilePondPluginFileValidateType
);
// 并在 create 选项中添加：
allowDownload: true, // 允许下载操作通过以上配置，FilePond 将把服务端已有文件渲染为只读、可下载的卡片，彻底解决“误当新文件上传”的问题，同时保障用户体验与数据一致性。
