下载按钮与加密下载
Firefly 支持在文章页放置下载按钮，每个文件都能单独设置访问密码。密码在构建期自动转成哈希，明文不会出现在任何产物里。
一、两种调用方式
下载按钮有两个入口：文章头部统一声明（正文下方自动生成下载区），或在正文任意位置内联插入。按你的排版需求选一个，两个也可以混用。
方式一：frontmatter 声明（推荐）
在文章头部用 downloads 字段声明下载项，文章渲染后会在正文下方自动生成「资源下载」区块：
---title: 我的文章downloads: - name: 示例压缩包 url: /downloads/demo.zip size: 4.2 MB password: your-password # 可选，独立于文章密码 hint: 提示信息 # 可选 icon: fa7-solid:file-zipper # 可选---一篇文章有多个文件就往数组里加几行，渲染出来就是一排按钮。
| 字段 | 必填 | 说明 |
|---|---|---|
name | 是 | 按钮上显示的文件名 |
url | 是 | 文件地址，支持站内绝对路径 /xxx、相对路径与 http(s) 外链 |
size | 否 | 文件大小展示文本，如 4.2 MB |
password | 否 | 该下载项的独立密码，留空则不加密 |
hint | 否 | 密码框里的一行提示，例如「密码见评论」 |
icon | 否 | 图标名，支持 Iconify 名称或关键字（file-zipper、image、code 等） |
方式二：::download{} 指令
在正文任意位置插入单个按钮，适合放在段落中间、列表里或代码块后面：
::download{name="内联按钮" url="/downloads/demo.zip" size="1.1 MB"}同样支持全部字段：
::download{name="加密资源" url="/downloads/protected.zip" password="firefly2025" hint="演示密码：firefly2025"}二、文件放哪里
要下载的文件放进 public/downloads/ 目录，构建时会原样复制到站点根目录：
public/downloads/demo.zip → 线上路径 /downloads/demo.zip所以 url 就写 /downloads/demo.zip。
Linux 服务器严格区分大小写，Demo.zip 和 demo.zip 是两个不同的文件。下载链接 404 大多出在这里。
大文件建议传到 CDN 或对象存储，再把外链填进 url，两种都支持：
downloads: - name: 大型资源包 url: https://cdn.example.com/packages/large.zip size: 128 MB三、加密下载是怎么工作的
你在 password 里写明文，剩下的构建时自动完成：
- 构建期把明文密码算成 SHA-256 哈希，只把哈希写进 HTML 的
data-dl-hash属性 - 明文密码不进入任何产物，查看网页源代码搜不到
- 读者点击按钮 → 弹出密码框 → 浏览器计算同样的哈希比对 → 通过才触发下载
- 密码错误时提示「密码错误，请重试。」，最多 3 次尝试机会
文章加密用 password 字段控制整篇正文；下载按钮的 password 只管这一个文件。两者互不影响。
四、实际效果演示
下面这组按钮就是本文档配套的示例，点开试试：
本文中加密按钮的密码是 firefly2025，可以直接复制到密码框验证完整流程：输错会看到错误提示，输对才会开始下载。
五、注意事项
密码是访问门禁，不是强加密
校验发生在浏览器端，懂技术的人查看源代码就能绕过。它的作用是防随手转发、给读者一点仪式感，不适合存放高价值机密。
如果需要真正的文件保护，把文件本身用 AES 加密或 zip 加密码后再上传，把地址填进 url，密码通过其他渠道告知读者。
图标名怎么填
icon 字段支持两种写法：
icon: fa7-solid:file-zipper # 完整 Iconify 名称icon: file-zipper # 关键字，自动匹配内置图标常用关键字：file-zipper、image、code、database、book、download。不填则使用默认的下载箭头图标。
六、常见问题
Q：密码写错了怎么办？
A：改 frontmatter 里的 password 后重新构建即可，线上立即生效。
Q：点击没反应？
A：多半是 url 指向的文件不存在。构建后到 dist/ 下确认文件是否被复制过去。
Q：能同时放很多文件吗？
A：可以，downloads 数组加多少行都行，移动端会自动换行。
Q：下载的文件需要登录才能下载吗？ A：不需要。按钮的密码校验是纯前端的，适合公开资源，不适合需要身份鉴权的场景。
支持与分享
如果这篇文章对你有帮助，欢迎分享给更多人或打赏支持！