oss_signature

轻量级阿里云 OSS URL 签名工具库，零依赖，支持浏览器和 Node.js 环境。

特性

• 纯前端实现，无需安装阿里云 OSS SDK
• 内置 HMAC-SHA1 签名算法
• 支持 STS 临时凭证（SecurityToken）
• 支持自定义过期时间、HTTP 方法和响应头覆盖
• 同时输出 ESM 和 CJS 格式

安装

npm install oss_signature
# 或
pnpm add oss_signature

快速开始

import { OssUrlSigner } from 'oss_signature';

const signer = new OssUrlSigner({
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  securityToken: 'your-security-token',
  region: 'oss-cn-shenzhen',
  bucket: 'your-bucket-name',
});

// 生成带签名的访问 URL
const url = signer.signatureUrl('path/to/object.png');
console.log(url);

API

new OssUrlSigner(options)

创建签名实例。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | accessKeyId | string | 是 | - | 阿里云 AccessKey ID | | accessKeySecret | string | 是 | - | 阿里云 AccessKey Secret | | securityToken | string | 是 | - | STS 临时安全令牌 | | region | string | 是 | - | OSS 区域，如 oss-cn-shenzhen | | bucket | string | 是 | - | Bucket 名称 | | secure | boolean | 否 | true | 是否使用 HTTPS 协议 |

signer.signatureUrl(name, options?)

生成带签名的资源访问 URL。

参数：

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | name | string | 是 | - | 对象路径，如 folder/image.png | | options.expires | number | 否 | 1800 | 签名有效期（秒） | | options.method | string | 否 | 'GET' | HTTP 请求方法 | | options.response | Record<string, string> | 否 | - | 覆盖响应头，如 { 'content-type': 'image/png' } |

返回值： string — 带签名的完整 URL

使用示例

基础用法 — 生成下载链接

const url = signer.signatureUrl('uploads/2024/report.pdf');
// https://your-bucket.oss-cn-shenzhen.aliyuncs.com/uploads/2024/report.pdf?OSSAccessKeyId=...&Expires=...&Signature=...

设置过期时间

// 链接有效期 1 小时（3600 秒）
const url = signer.signatureUrl('uploads/photo.jpg', {
  expires: 3600,
});

覆盖响应头

// 强制浏览器以附件形式下载
const url = signer.signatureUrl('uploads/document.docx', {
  response: {
    'content-disposition': 'attachment; filename="document.docx"',
    'content-type': 'application/octet-stream',
  },
});

使用 HTTP 协议

const signer = new OssUrlSigner({
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  securityToken: 'your-security-token',
  region: 'oss-cn-shenzhen',
  bucket: 'your-bucket-name',
  secure: false, // 使用 http://
});

注意事项

• 本库使用 STS 临时凭证签名，请确保 securityToken 未过期
• 签名 URL 的有效期由 expires 参数控制，同时受 STS Token 有效期约束
• 建议将敏感凭证（AccessKeySecret 等）通过后端接口获取，避免硬编码在前端

许可证

ISC