用 Neon Object Storage…

当应用已用 Neon/Lakebase Postgres、需要上传/图片/文档等文件存储且希望文件与数据库跨分支同步时，用 Neon 内置的 S3 兼容对象存储替代 AWS S3/R2/Supabase Storage。

适用场景

解决思路

1. 先确认前置条件：Neon Object Storage 目前仅在 aws-us-east-2、aws-us-east-1、aws-eu-central-1、aws-ap-southeast-1 可用，确认用户项目在这些区域之一再继续。
2. 在 neon.ts 基础设施即代码文件中用 buckets 块声明桶（按桶名作 key），例如 images: {} 为默认私有，"public-assets": { access: "public_read" } 为公开读；然后运行 neon deploy（即 neon config apply 的别名）在已链接分支上创建声明的桶。
3. 用 Terraform 式流程对分支做声明式协调：neon config status 查看分支当前实际配置（有哪些桶）、neon config plan 做 apply 前的 dry-run 差异、neon config apply 创建声明的桶。
4. 注意桶是分支作用域的：存在 neon.ts 时，neon checkout 在创建分支时会应用策略，使新的 preview/CI 分支自带已创建的桶并从父分支继承写时复制对象；但 checkout 已存在的分支不会做协调，需运行 neon deploy 应用变更。
5. 获取环境变量：部署在 Neon Function 中会自动注入；本地用 neon env pull 写入 .env（或 .env.local），或用 neon-env run -- <你的开发命令> 在运行时注入而不落盘。
6. 使用注入的 AWS 标准环境变量：AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_ENDPOINT_URL_S3、AWS_REGION；AWS SDK 会自动从环境读取凭证、端点与区域，凭证是分支作用域且对该分支及其所有后代有效。
7. 如需类型化、校验过的凭证访问，把同一份 neon.ts 配置对象传给 @neon/env 的 parseEnv，得到 env.storage 命名空间（accessKeyId、secretAccessKey、endpoint、region），而不是直接读 process.env。
8. 推荐用 Files SDK 的 neon 适配器读写对象：先安装 npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner，然后用 new Files({ adapter: neon({ bucket: "images" }) }) 创建实例，调用 upload、download、url、list、exists、copy、delete、signedUploadUrl；适配器从注入的 AWS_* 环境变量解析端点、区域和凭证，只需传桶名。
9. 也可直接用 AWS S3 客户端：创建 S3Client 时必须设置 forcePathStyle: true（Neon 使用 path-style 寻址），凭证/端点/区域从标准 AWS 环境链读取；用 PutObjectCommand 上传、GetObjectCommand 下载、getSignedUrl 生成预签名 GET（如 expiresIn: 3600）。
10. 采用与数据库配对的经典模式：agent 生成图片 → PutObject 写入 images 桶 → 在 Postgres 插入一行 → 读取时返回预签名 URL；在 Postgres 列中存桶的 key（而非字节），读取时再预签名，因为行和对象在同一分支上会一起分支、永不漂移。
11. 公开资源要加 CDN：public_read 对象可通过 ${AWS_ENDPOINT_URL_S3}/<bucket>/<object-key> 匿名读取，把该分支存储端点作为 Cloudflare 或 Vercel CDN 的源，并在 PutObject 时设置 Cache-Control；缓存对象的新鲜度取决于 key，所以每个版本写到新 key（如 avatars/<user-id>/<uuid>.jpg）并在 Postgres 中重指向该 key，而不是覆盖同一 key 等 TTL 过期；生产 CDN 指向生产分支，preview 分支直接读自己的端点而不共享缓存；私有桶则继续用查询串携带签名的预签名 URL。
12. 用 CLI 做桶和对象操作：neon bucket create|list|delete 与 neon bucket object put|get|list|delete，适合脚本和一次性操作。
13. 用内置分支日志排查存储问题：neon logs query --branch production --source storage --since 1h；日志按分支作用域，调试的桶不在当前 checkout 的分支时需传 --branch。
14. 始终以官方文档为准并核对：Neon 文档是事实来源且 Object Storage 演进很快，任意文档页可在 URL 后加 .md 或请求 Accept: text/markdown 获取 markdown，从 https://neon.com/docs/llms.txt 索引和 changelog 公告找页面。

适用边界 · 注意事项

• 文件是随应用一起发布的静态资源（HTML、JS bundle、CSS、public/ 中的图片字体）时不要用——那属于静态网站托管，应放在 Vercel、Netlify 或 Cloudflare；Neon 没有网站模式，PutBucketWebsite 会返回 501 Not Implemented。
• 用户项目不在 aws-us-east-2、aws-us-east-1、aws-eu-central-1、aws-ap-southeast-1 这四个区域时不可用。
• 需要托管应用本身（index 文档、SPA fallback、自定义域名）时不要用，应放到 Vercel、Netlify 或 Cloudflare。