上传并使用图片与文件

媒体库是什么

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

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

文件在上传后立即公开，即使还没有任何页面引用。仅上传所有访客都可以查看的内容——切勿上传包含电话号码的简历、证件或私密文件。

在控制台中

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

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

• Cover image —— 在 Details 中选择 Choose or upload a cover image。它会显示在条目页面顶部。
• Gallery —— 使用 Add photo or video 添加与正文并排显示的项目，每个都有 alt 文本和可选说明。
• Proof file —— 在 proof 行中，回形针图标可附加已上传的 PDF（例如论文）。
• Inside the text —— 编辑器工具栏中的图片按钮可插入图片；你也可以将图片直接拖入或粘贴到正文中。选中已插入的图片可编辑其 alt 文本。

像往常一样，保存条目即发布更改。编辑器会拒绝保存指向不存在的 /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）

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

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

向代理发出的典型请求：“上传 ~/Desktop/xero-talk.jpg，alt 文本为『Jenks speaking at Xerocon』（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.xyz/api/admin/media

对 /api/admin/media 的 GET、PATCH 和 DELETE 分别用于列出、更新和删除。参见管理 API 参考。

安全删除

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

used by 检查会读取此环境上次部署的内容。dev 与 production 共享同一个媒体库（因此在 dev 预览期间上传的文件在你提升后仍可使用），所以仅被未提升的 dev 内容使用的文件，在 production 控制台中可能会显示为未使用。