文件存储与内容管理
你的应用有专用的内容文件系统,用于存储用户上传的文件,例如图片、文档、PDF 和视频。它与你的应用代码分开,专为用户在使用应用时创建或上传的动态内容而设计。
限制和重要说明
- 单个文件大小最高可达 500MB
- 文件删除是永久操作,没有废纸篓或回收站
- 存储用量会计入你的账户配额
内容文件系统能做什么
内容文件系统为你的应用提供强大的文件管理能力:
- 存储用户头像、个人资料照片和图片图库
- 接受文档上传,例如简历、合同或 PDF
- 在应用用户之间构建文件共享功能
- 创建图片密集型应用,并自动优化图片
- 让用户下载他们上传的文件或属于他们的文件
- 构建管理工具,让你代表用户管理文件
工作方式
当你向 AI 描述一个需要文件存储的功能时,它会自动处理完整实现:
设置上传界面 —— 创建表单或拖放区域,让用户可以从自己的设备选择文件
配置访问控制 —— 根据你正在构建的内容,确定谁可以查看、上传或删除文件
实现图片优化 —— 自动调整图片尺寸并高效提供图片,让你的应用加载更快
创建存储结构 —— 将文件整理到逻辑文件夹中,例如 /content/uploads/ 或 /content/avatars/
处理后台 —— 管理实际的文件存储、检索和交付,你无需考虑这些细节
文件会存储在类似 /content/uploads/photo.jpg 的路径下,并可在你的应用中直接引用。系统会跟踪每个文件由谁上传、何时创建,并执行你的访问规则。
文件访问控制
与数据库表和边缘函数一样,文件也有安全策略,用于控制谁可以访问它们。文件默认是私有的 —— 在你配置权限之前,任何人都不能访问。AI 会根据你正在构建的内容设置这些策略:
公开文件
任何人都可以查看,即使没有登录也可以。已登录用户可以上传,只有上传文件的人可以删除它。非常适合照片图库、公开图片共享或用户生成内容网站。
私有文件
只有上传文件的用户可以查看或删除它。用于敏感文档、私人照片、医疗记录,或任何用户不希望其他人看到的内容。
组织共享文件
同一组织中的用户可以查看其组织内任何人上传的文件。个人只能删除自己上传的文件。适合团队文档共享、公司资源或协作工作区。
仅所有者访问
只有你(应用创建者)可以访问这些文件,你的最终用户不能访问。适合存储系统文件、模板,或支撑应用但不应面向用户的管理资源。
高级访问控制
AI 可以基于文件元数据创建更细致的访问规则。例如:
- 已发布文章是公开的,但草稿只有作者可见
- 带有部门标签的文件只对该部门用户可见
- 高级内容要求用户账户上有订阅标记
- 共享文件对文件元数据中列出的协作者可见
图片优化
上传到内容文件系统的图片会自动优化,以便快速加载。显示图片时,你可以请求特定宽度,系统会处理其余工作:
<!-- Thumbnail (200px wide) -->
<img src="/content/gallery/photo.jpg?w=200" />
<!-- Standard display (800px wide) -->
<img src="/content/gallery/photo.jpg?w=800" />
<!-- Hero image (1920px wide) -->
<img src="/content/gallery/photo.jpg?w=1920" />
<!-- Original, full-size image -->
<img src="/content/gallery/photo.jpg" />
优化如何工作
渐进式加载 —— 某个优化尺寸第一次被请求时,系统会提供最接近的可用版本,并在后台生成精确尺寸。之后的每次请求都会获得尺寸恰好合适且已优化的图片。原始文件始终会被保留。
现代格式交付 —— 系统会自动向支持的浏览器提供现代图片格式(AVIF 或 WebP),并为较旧浏览器自动回退到 JPEG 或 PNG。这个过程对你透明:你只需指定宽度,用户就会获得其浏览器能够处理的最快加载版本。
性能优化 —— 使用较小宽度来提升性能。200px 缩略图比原始 4000px 图片加载快得多,并且占用更少带宽。选择与你显示图片方式匹配的宽度。
在你的应用中使用文件
AI 会自动把内容文件系统集成到你的 React 应用中。当你请求涉及文件的功能时,它会创建 UI 组件,接好上传/下载逻辑,并处理错误。
AI 实现的常见模式
头像上传 —— 个人资料照片上传界面,可验证图片类型、显示上传进度、预览图片,并将路径保存到用户资料。
文档图库 —— 文件浏览器,可列出已上传文档、为图片显示缩略图、提供下载链接,并允许筛选或搜索。
拖放上传 —— 直观的上传区域,用户可以从桌面拖入文件、查看上传进度、取消正在进行的上传,并收到无效文件的错误消息。
文件选择器 —— 模态框或侧边栏,显示用户此前上传的文件,允许他们选择一个文件复用,并显示缩略图和文件名。
边缘函数集成
边缘函数(你的服务端代码)可以访问内容文件系统,以处理文件、以编程方式生成文件,或实现自定义文件处理逻辑。
边缘函数可以对文件做什么
- 生成 PDF 报告并保存,供用户下载
- 处理上传的图片(应用水印、创建缩略图、提取元数据)
- 在接受上传文档之前扫描其中的敏感数据
- 实现自定义备份或归档逻辑
- 分析文件内容并提取结构化数据
- 在特定文件上传时触发工作流
警告: 重要安全说明
边缘函数会绕过常规访问控制。当你的函数访问文件时,它不受适用于用户的“公开”或“所有者”规则限制。这意味着你必须在函数代码中实现自己的授权检查,确保用户只能访问他们应当看到的文件。
例如,如果用户调用你的函数请求某个文件,你需要在返回内容之前确认他们拥有该文件,或有权限访问该文件。AI 在构建你的函数时会处理这一点,但理解函数代码以提升后的权限运行很重要。
存储组织
AI 会根据你正在构建的内容,把文件整理到逻辑文件夹中。你不需要手动创建文件夹结构;只需描述需要什么,AI 就会设置合适的路径。
常见组织模式
/content/uploads/—— 通用用户上传/content/avatars/—— 用户个人资料照片/content/documents/—— PDF 和文档/content/gallery/—— 照片图库图片/content/private/—— 私有用户文件/content/public/—— 可公开访问的文件/content/temp/—— 可以删除的临时文件
在适合你的用例时,AI 可以创建类似 /content/uploads/2024/ 或 /content/users/[username]/ 的嵌套文件夹。文件会按完整路径跟踪,因此移动或重命名文件会自动更新所有引用。
监控和调试
所有文件操作都会被记录:上传、下载、拒绝访问和错误。你可以在管理界面查看这些日志,了解文件存储的使用情况:
- 查看哪些文件上传最频繁
- 识别失败的上传以及出错原因
- 跟踪下载模式和热门文件
- 随时间监控存储用量和增长
- 在用户无法访问预期文件时调试访问控制问题
系统还会跟踪存储指标:已存储文件总数、总大小、增长率和最大文件。这有助于你了解应用的存储占用,并为扩展做规划。
限制和约束
默认情况下,单个文件大小最高可达 500MB。这可以配置;AI 可以根据你正在构建的内容调整限制。对多数应用(图片上传、文档共享、PDF)来说,默认限制已经绰绰有余。
为保证可靠性,文件会进行冗余存储。如果删除文件,它会从系统中永久移除;没有废纸篓或回收站,因此删除会立即生效且不可撤销。
与 AI 协作
描述需要文件存储的功能时,请具体说明:
- 谁可以访问文件 —— 公开、私有、组织共享,或自定义规则
- 哪些文件类型 —— 仅图片、PDF、任何文件类型、大小限制
- 文件如何组织 —— 文件夹、命名约定、用户是否可以创建子文件夹
- 上传后发生什么 —— 显示在图库中、附加到记录、用函数处理
AI 会使用这些信息正确配置存储、设置访问策略,并创建与你需求匹配的界面。
相关文档: