上传并使用图片与文件

媒体库是什么

上传的文件存放在 Cloudflare R2 存储桶中，并从 https://jenksguo.pages.dev/media/… 提供访问。 支持：WebP、JPEG、PNG、GIF、AVIF 和 SVG 图片，MP4 和 WebM 视频，以及 PDF——单个文件最大 25 MB。 实际类型从文件内容读取，因此仅通过重命名无法把其他文件伪装成图片。

每个文件都会得到一个永久地址，例如 /media/2026/10/acme-workshop-3f9a1c2b7d.webp。最后一段是该文件字节的指纹，因此同一地址永远不会指向不同内容，浏览器可以将其缓存一年。再次以上传时使用同名同内容的文件会复用已存在的副本。

文件一经上传即公开可见，即使还没有任何页面引用它。仅上传可以向所有访客公开的内容——切勿上传包含电话号码的简历、身份证件或任何私密文件。

在控制台中

1. 打开 https://admin.jenksguo.xyz/admin（使用 Google 登录），并在顶部栏选择 Media。
2. 将文件拖到页面上、粘贴截图，或点击 Upload。在开启 Optimise photos（默认）时，照片会先在你的浏览器中被调整到 2400 像素并转换为 WebP——一张 6 MB 的手机照片通常会变为 300–600 KB。iPhone 的 HEIC 照片在浏览器可读取时（例如 Safari）会被转换。
3. 选择一个文件以添加 alt text——用一句话描述图片展示的内容。读屏软件和 Ask Jenks 助手会使用它。

然后在 Content 编辑器中使用这些文件：

• 封面图——在“Details”中选择“Choose or upload a cover image”。它会显示在条目页面顶部。
• 图库——“Add photo or video” 可添加在正文旁显示的项目，每个都有 alt text 和可选的说明文字。
• 证明文件——在证明行中，回形针图标可附加已上传的 PDF（例如论文）。
• 正文内——编辑器工具栏中的图片按钮可插入图片；你也可以将图片直接拖入或粘贴到正文中。选中已插入的图片可编辑其 alt text。

像往常一样，保存条目即发布更改。编辑器会拒绝保存指向不存在的 /media/… 文件的内容。

通过 CLI

jenks admin media upload ~/Pictures/acme-workshop.jpg --alt "Jenks running an AI workshop at Acme"
jenks admin media upload https://example.com/talk-poster.png     # the server fetches it
jenks admin media ls                                            # newest first, with "used by"
jenks admin media alt 2026/10/acme-workshop-3f9a1c2b7d.jpg "New alt text"
jenks admin media rm 2026/10/acme-workshop-3f9a1c2b7d.jpg

CLI 会按原样上传文件（不做尺寸调整），因此请先将大照片按合理尺寸导出。然后在条目中引用打印出的 url：

image: /media/2026/10/acme-workshop-3f9a1c2b7d.jpg
imageAlt: Jenks running an AI workshop at Acme
gallery:
  - src: /media/2026/10/acme-team-0c1d2e3f4a.webp
    alt: The Acme leadership team at the kick-off
    caption: Kick-off, October 2026

通过 AI 代理（MCP）

管理 MCP 服务器提供 admin_upload_media、admin_list_media、admin_update_media 和 admin_delete_media。

• 本地（jenks mcp --admin）：通过 path 传入你电脑上的文件——本地服务器会为代理读取它。
• 远程（/mcp/admin）：通过 url（要导入的 https 地址）或携带 filename 的 data（base64）传入。

对代理的典型请求：“上传 ~/Desktop/xero-talk.jpg，alt text 设为‘Jenks 在 Xerocon 演讲’，然后将其设为 xero-developer-evangelist 的封面图。”

通过 REST

curl -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -F file=@acme-workshop.jpg -F alt="Jenks running an AI workshop at Acme" \
  https://jenksguo.pages.dev/api/admin/media

对 /api/admin/media 的 GET、PATCH 和 DELETE 可用于列出、更新和删除。参见 admin API reference。

安全删除

删除是永久性的：与内容不同，文件没有 git 历史。控制台和 API 会拒绝删除仍被已发布内容使用的文件，并显示其使用位置。请先移除这些引用；或者如果你接受出现损坏的图片，可以强制删除。

“used by” 检查会读取此环境上次部署的内容。开发环境和生产环境共用一个媒体库（因此在 dev 预览时上传的文件，在你提升到生产后仍可用），所以仅被未提升到生产的 dev 内容使用的文件，可能会在生产控制台中显示为未使用。