Next.js客户端如何获取Strapi媒体库文件的可下载链接

核心前提：获取Strapi文件的可访问链接 #

Strapi本身的API返回结构已经内置了媒体文件的访问路径，不需要额外找特殊入口：

• 所有上传到Strapi媒体库的文件，在接口返回时都会携带url字段，存储文件的访问路径
• 如果你是给自定义内容类型添加了媒体类型字段，请求内容接口时必须带上populate参数关联媒体字段，否则接口默认不会返回媒体相关数据，示例请求：GET /api/your-content-slug?populate=target_media_field
• 接口返回的媒体字段结构参考如下：

{
  "file_field": {
    "data": {
      "id": 32,
      "attributes": {
        "name": "项目说明文档.pdf",
        "url": "/uploads/xiangmu_shuoming_8b2d91.pdf",
        "mime": "application/pdf",
        "size": 1240.5,
        "ext": ".pdf"
      }
    }
  }
}

注意：如果Strapi用本地存储，返回的url是相对路径，需要拼接你部署的Strapi服务根地址才是完整可访问链接；如果配置了第三方对象存储（S3、OSS等），返回的url本身就是公网可访问的完整地址，不需要额外拼接。

Next.js客户端下载实现 #

直接用a标签跳转文件链接的话，PDF、图片类文件会被浏览器直接预览，不会触发下载，建议用Blob方式实现强制下载，客户端组件示例代码：

'use client'

interface DownloadButtonProps {
  // 拼接好的完整文件访问地址
  fileFullUrl: string
  // Strapi返回的文件原始名称，用来保证下载后文件名正确
  fileName: string
}

export default function DownloadButton({ fileFullUrl, fileName }: DownloadButtonProps) {
  const handleDownload = async () => {
    try {
      const response = await fetch(fileFullUrl)
      if (!response.ok) throw new Error('文件请求失败')
      const fileBlob = await response.blob()
      const tempUrl = window.URL.createObjectURL(fileBlob)
      const linkEl = document.createElement('a')
      linkEl.href = tempUrl
      linkEl.download = fileName
      document.body.appendChild(linkEl)
      linkEl.click()
      // 释放临时对象，避免内存占用
      window.URL.revokeObjectURL(tempUrl)
      document.body.removeChild(linkEl)
    } catch (error) {
      console.error('下载出错:', error)
      // 这里可以加自己的错误提示逻辑
    }
  }

  return (
    <button onClick={handleDownload} type="button">
      下载文件
    </button>
  )
}

特殊场景处理 #

• 如果Strapi媒体库配置了非公开权限，不要把带权限凭证的文件地址直接暴露给前端，可以在Next.js里写一个服务端Route Handler，校验完当前用户权限后，再从服务端请求Strapi文件流返回给前端
• 如果需要做防盗链、临时链接过期控制，直接在你用的对象存储侧配置签名规则即可，Strapi上传插件支持自定义适配返回的链接格式
• 如果是大文件下载，建议改用分片下载逻辑，避免前端fetch的时候占用过多内存导致页面卡顿

内容的提问来源于stack exchange，提问作者Suraj Suddala