#文件

NocoBase 3 提供文件上传、文件信息管理和下载能力，可以用来处理员工头像、产品图片、订单附件等业务需求。

文件表、上传入口和展示方式可以按业务需要定制。你只需要向 Coding Agent 说明文件用在哪里、每条记录需要一个还是多个文件，以及希望怎样展示，由它完成建表和页面接入。

#给业务添加附件

比如，已有一个订单管理页面，希望每个订单都能上传附件，可以这样描述：

给订单增加附件功能，使用 NocoBase 的文件能力。

创建订单附件表，每个订单可以关联多个附件。
在订单详情中支持批量上传，显示文件名和大小，并提供预览、下载和移除入口。
移除时只解除附件与订单的关联，暂时保留文件。
页面样式沿用现有订单页面。

Coding Agent 需要接入的不只是上传按钮，还包括文件表、订单与附件的关系，以及对应的上传和访问接口。如果项目已经有可复用的文件表或上传界面，可以让它在现有功能上调整，不必重新创建。

#文件表需要哪些字段

文件表是一张记录文件信息的数据表，实际文件内容不保存在这张表里。 每个文件对应一条记录，保存文件名、大小和存储位置等信息。

表名可以按业务命名，比如 orderAttachments、productImages。下面这些字段的名称是固定的，建表时需要保留，上传时由文件能力自动填写。

你不需要手动填写这些值，也不必自己生成文件地址。contentUrl 是文件能力根据 id 和 ext 生成的访问地址，不需要为它创建数据库字段。让 Coding Agent 查询时保留这两个字段；如果它自定义了返回字段，或在服务端直接读取文件记录，要确认访问地址仍然可用。

可以在标准字段之外增加业务字段，比如订单编号、分类或备注。上传时只写入标准文件字段，因此额外字段需要允许为空，或者有默认值，不能要求上传时必须填写。

#单个文件与多个文件

每条业务记录需要多少个文件，会影响文件与业务数据的关联方式。

单个文件适合员工头像、产品封面等场景。一条业务记录最多关联一个文件；上传新文件时，可以按需要替换原来的关联。例如：

给员工增加头像，每名员工最多一张。
支持上传和更换头像，在员工列表和详情中显示。
更换后使用新头像，刷新页面后仍能正常显示。

多个文件适合订单附件、产品相册等场景。一条业务记录可以关联多条文件记录，每个文件都能单独查看或移除。前面的订单附件就是这种用法。

以订单附件为例，可以在附件表中增加 orderId，记录文件属于哪个订单。这个字段需要允许为空：先上传文件，再将文件与订单关联。具体的关系配置和保存过程交给 Coding Agent 完成。

替换或移除关联，不代表旧文件已经被彻底删除，具体区别见下方的常见问题。

#预览和下载

可以让 Coding Agent 在表单、列表或详情页中加入文件预览。文件组件提供图片、PDF、文本、Markdown、音频和视频等预览方式；具体页面需要接入相应组件，不是建好文件表就会自动出现。

DOCX、XLSX、PPTX 支持在浏览器内本地预览，无需 Office Online；内网仍需能访问应用和文件服务。旧版 DOC、XLS、PPT 及 OpenDocument 格式可使用 Office Online（需要外网可访问的文件地址），或下载查看。

描述需求时可以说：「产品图片显示缩略图，点击后放大」「订单附件显示文件列表，支持预览和下载」。

并不是所有格式都能直接预览。不支持的格式可以保留下载入口；HTML、SVG、XML 等可能包含活动内容的文件，不直接内嵌预览。

#文件存放在哪里

文件信息保存在数据库中，实际文件保存在应用配置的存储位置。项目的文件示例使用本地存储，也可以按应用的存储配置进行调整。

需要更换存储位置时，告诉 Coding Agent 哪类文件要使用哪个存储配置即可。更改新上传文件的存储位置，不会自动迁移旧文件。 如果旧文件也需要搬迁，要把迁移需求一并说明。

备份时也需要同时考虑数据库和实际文件，不能只备份文件表。

#文件的访问权限

如果附件包含合同、员工资料等非公开内容，要同时说明谁可以上传、查看、下载和删除，以及可以操作哪些记录。例如：「只有订单负责人和管理员可以访问该订单的附件」。

#常见问题

#文件上传成功了，为什么业务记录里还没有附件？

上传文件和保存业务记录是两个步骤。上传成功后，文件记录已经创建；页面还需要把它与对应的业务记录关联。

如果取消表单，已上传的文件不会因此自动删除。需要自动清理未关联文件时，应让 Coding Agent 按业务要求补充清理规则。

#移除附件，会把文件一起删除吗？

不一定，要区分三种操作。

移除关联只让附件不再属于这条业务记录，文件记录和实际文件仍保留。删除文件记录会删除数据库中的记录，但当前文件插件不会同时删除存储中的实际文件。彻底清理文件需要应用另外实现。

因此，描述删除需求时，应明确是「从当前订单移除」，还是「同时清理文件记录和实际文件」。如果文件可能被其他记录引用，还要说明是否允许删除。

#较大的文件上传失败，怎么办？

内置上传接口默认限制单文件上传请求为 5 MiB、批量上传请求为 20 MiB。限制的是整个请求的大小，包含附加信息；批量上传不是每个文件都可以达到 20 MiB。

可以减少一次上传的文件数量，或者让 Coding Agent 调整上传限制。如果还要求「每个文件最多多大」「每条记录最多几个附件」或「只允许哪些格式」，需要把这些业务规则另外说明，并同时检查页面提示和服务端校验。