{"_id":"@acgrid/cos-js-sdk-v5","name":"@acgrid/cos-js-sdk-v5","dist-tags":{"latest":"1.10.1"},"versions":{"1.10.1":{"name":"@acgrid/cos-js-sdk-v5","version":"1.10.1","description":"JavaScript SDK for [腾讯云对象存储](https://cloud.tencent.com/product/cos)","main":"dist/cos-js-sdk-v5.js","types":"index.d.ts","scripts":{"prettier":"prettier --write src demo/demo.js demo/CIDemos/*.js test/test.js server/sts.js lib/request.js index.d.ts","server":"node server/sts.js","server:env":"node -r dotenv/config server/sts.js","dev":"cross-env NODE_ENV=development webpack -w --mode=development","build":"cross-env NODE_ENV=production webpack --mode=production","cos-auth.min.js":"uglifyjs ./demo/common/cos-auth.js -o ./demo/common/cos-auth.min.js -c -m","test":"jest --runInBand --coverage","test:env":"node -r dotenv/config ./node_modules/jest/bin/jest.js --runInBand --coverage","postinstall":"node scripts/patch-check.js"},"repository":{"type":"git","url":"git+https://github.com/acgrid/tencent-cos-js-sdk-v5.git"},"keywords":[],"author":{"name":"carsonxu"},"license":"ISC","bugs":{"url":"https://github.com/acgrid/tencent-cos-js-sdk-v5/issues"},"homepage":"https://github.com/acgrid/tencent-cos-js-sdk-v5#readme","dependencies":{"@babel/runtime":"^7.29.7","fast-xml-parser":"^5.9.2"},"devDependencies":{"@babel/core":"^7.29.7","@babel/plugin-transform-runtime":"^7.29.7","@babel/preset-env":"^7.29.7","babel-loader":"8.2.5","body-parser":"^1.18.3","cross-env":"^5.2.0","dotenv":"^16.4.7","express":"^4.16.4","jest":"29.7.0","jest-environment-jsdom":"29.7.0","patch-package":"^8.0.0","prettier":"^3.0.1","qcloud-cos-sts":"^3.0.2","request":"^2.87.0","terser-webpack-plugin":"4.2.3","uglifyjs":"^2.4.11","webpack":"4.46.0","webpack-cli":"4.10.0"},"gitHead":"bab1ee3db3dc780a31115a1e3fd5f4cb5294e8fd","_id":"@acgrid/cos-js-sdk-v5@1.10.1","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-S1IyBfK5jYaITnIWIU8Nv7vYswIHZe8N0XwW1oBlr1oZ5BeGyhSrz3nYkfLVjsICQC27TyCHhiziWVKettM8Ng==","shasum":"f061cf49f3a05a99c32ccf00af0d814832364eff","tarball":"https://registry.npmjs.org/@acgrid/cos-js-sdk-v5/-/cos-js-sdk-v5-1.10.1.tgz","fileCount":22,"unpackedSize":1390967,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDRiYCMISkSogR1AOoMcJZlNkY8/eReUuNsVGkC/hPV+wIhAPIqLDZjWf39eBtKtO2ZapfWes2L5l8O88LfJWzZ5GcZ"}]},"_npmUser":{"name":"acgrid","email":"acgrid@gmail.com"},"directories":{},"maintainers":[{"name":"acgrid","email":"acgrid@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cos-js-sdk-v5_1.10.1_1782109631128_0.8686933275402298"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-22T06:27:11.028Z","1.10.1":"2026-06-22T06:27:11.266Z","modified":"2026-06-22T06:27:11.427Z"},"maintainers":[{"name":"acgrid","email":"acgrid@gmail.com"}],"description":"JavaScript SDK for [腾讯云对象存储](https://cloud.tencent.com/product/cos)","homepage":"https://github.com/acgrid/tencent-cos-js-sdk-v5#readme","keywords":[],"repository":{"type":"git","url":"git+https://github.com/acgrid/tencent-cos-js-sdk-v5.git"},"author":{"name":"carsonxu"},"bugs":{"url":"https://github.com/acgrid/tencent-cos-js-sdk-v5/issues"},"license":"ISC","readme":"# cos-js-sdk-v5\n\n腾讯云 COS JS SDK（[XML API](https://cloud.tencent.com/document/product/436/7751)）\n\n[releases and changelog](https://github.com/tencentyun/cos-js-sdk-v5/releases)\n\n## 本分支依赖迁移说明\n\n### 迁移动机\n\n本分支用于维护一个长期未同步上游的 fork。原 SDK 依赖的 `fast-xml-parser` 版本较旧，已经不适合继续作为浏览器端 XML 解析基础。本次迁移的目标是参考 `@acgrid/cos-nodejs-sdk-v5` 的依赖升级结果，在尽量保持原有 JS SDK API 和打包产物形态的前提下，升级 XML 解析依赖，并补齐一套可以使用私有 `.env`、自建 STS 服务和真实 COS 测试桶重复运行的验证流程。\n\n### 主要改动\n\n- 将运行时 XML 解析依赖升级到 `fast-xml-parser@^5.9.2`，并移除旧的 `patch-package` 补丁。\n- 调整 webpack 4 构建，让 `fast-xml-parser` 及其现代语法依赖在浏览器包里经过 Babel 转译。\n- 新增 `server:env`、`test:env` 和 `.env.example`，测试时可以通过私有 `.env` 提供 `SecretId`、`SecretKey`、`Bucket`、`Region`、`jssdkStsUrl` 等配置。\n- 参考 NodeJS SDK 的测试 STS helper，给本地 STS 服务补齐 CORS 响应和 `OPTIONS` 预检支持。\n- 修复旧式 `AppId`/短 bucket 兼容边界：当短 bucket 名本身以数字结尾时，显式传入的 `AppId` 仍会被正确拼接。\n- 将依赖特殊云上资源的测试改为显式 opt-in，例如自定义域名和历史外部 retry fixture。\n- 增加媒体处理测试 fixture 的环境变量配置，并修复非 `RawBody` 场景下 m3u8 文本成功返回不能合并响应元数据的问题。\n\n### 测试手册\n\n以下测试说明面向源码仓库 checkout，不属于安装后的 npm 包运行时功能。请使用专门的 COS 测试桶，不要使用生产桶。\n\n```bash\ncp .env.example .env.local\n\n# 编辑 .env.local，至少填写：\n# SecretId / SecretKey / Bucket / Region / ReplicationBucket / ReplicationRegion / Uin\n# jssdkStsUrl=http://127.0.0.1:3300\n```\n\n如果没有现成的 STS 测试服务，可以使用本仓库 `server/sts.js`，或使用同级 NodeJS SDK 仓库里的 `test/sts-server.js`。使用 NodeJS SDK helper 时，需要让临时密钥覆盖 JS SDK 测试路径：\n\n```bash\nDOTENV_CONFIG_PATH=/path/to/tencent-cos-js-sdk-v5/.env.local \\\nSTS_PORT=3300 \\\nSTS_ALLOW_PREFIX=js-sdk/test/ \\\nnode -r /path/to/tencent-cos-js-sdk-v5/node_modules/dotenv/config test/sts-server.js\n```\n\n然后在 JS SDK 仓库运行：\n\n```bash\nDOTENV_CONFIG_PATH=.env.local npm run test:env\n```\n\n可选的环境变量如下：\n\n- `COS_RUN_BUCKET_DOMAIN_TESTS=1`：运行自定义域名测试，需要配置可用且已备案/审核通过的域名。\n- `COS_BUCKET_DOMAIN_REST` / `COS_BUCKET_DOMAIN_WEBSITE`：自定义域名测试使用的真实域名。可以只配置其中一个。\n- `COS_RUN_RETRY_TESTS=1`：运行历史外部 retry fixture 测试。\n- `COS_RETRY_BUCKET` / `COS_RETRY_REGION`：历史 retry fixture 的桶和地域；默认值仍是上游旧测试桶。\n- `COS_RAW_BODY_MP4_KEY`：媒体处理 snapshot 测试使用的 mp4 对象，默认 `2221333test.mp4`。\n- `COS_RAW_BODY_M3U8_KEY`：媒体处理 pm3u8 测试使用的 m3u8 对象，默认 `2视频/peachtest.mp4.m3u8`。\n\n### 测试结果与注意事项\n\n本次迁移使用真实 COS 测试桶、本地 STS 服务和本地生成的无版权风险媒体 fixture 做过回归。已验证的关键结果包括：\n\n```text\nnpm audit --omit=dev --json\n# production dependencies: 0 vulnerabilities\n\nnpm run test:env -- --runTestsByPath test/test.js -t \"putObject\\\\(\\\\) options.AppId|putObject\\\\(\\\\) BucketShortName\" --coverage=false\n# 2 passed\n\nnpm run test:env -- --runTestsByPath test/test.js -t \"BucketDomain\" --coverage=false\n# 5 passed, with COS_RUN_BUCKET_DOMAIN_TESTS=1 and real domain env\n\nnpm run test:env -- --runTestsByPath test/test.js -t \"RawBody error|returnBody\" --coverage=false\n# 8 passed\n\nNODE_OPTIONS=--openssl-legacy-provider npm run build\n# passed on the local Node.js 24 / webpack 4 environment\n```\n\n测试过程中遇到并处理了以下边界情况：`jssdkStsUrl` 可以对接 Node.js 自建 STS 服务，但浏览器/JSDOM 测试必须有 CORS 和 `OPTIONS` 预检响应；短 bucket 名如果本身以数字结尾，旧兼容逻辑会误判为完整 bucket；自定义域名测试必须使用真实、可审核通过的域名，不能继续使用上游占位域名；媒体处理测试需要真实可处理的 mp4/m3u8 对象；CI dataset 相关接口仍依赖额外数据集资源，当前只验证错误 body 解析。\n\n基于以上验证，本分支对 `fast-xml-parser` 升级和浏览器打包兼容性有较高信心，适合继续作为本 fork 的依赖维护版本。但这不是腾讯云官方发布版本，且浏览器端业务对历史兼容行为更敏感。如果客户端代码依赖短 bucket/AppId 老写法，或业务路径依赖媒体处理、CI、私有部署域名 CSP 等能力，不建议直接将生产业务切换到本 fork；请先保留现有版本，针对真实浏览器、真实 STS、真实 bucket CORS 和业务用到的 COS/CI 接口做完整回归。\n\n## Get started\n\n### 一、前期准备\n\n1. 首先，JS SDK 需要浏览器支持基本的 HTML5 特性，以便支持 ajax 上传文件和计算文件 md5 值。\n2. 到 [COS对象存储控制台](https://console.cloud.tencent.com/cos) 创建存储桶，得到 Bucket（由bucketname-appid 组成，appid必须填入） 和 [Region（地域名称）](https://cloud.tencent.com/document/product/436/6224)\n3. 到 [控制台密钥管理](https://console.cloud.tencent.com/capi) 获取您的项目 SecretId 和 SecretKey\n4. 配置 CORS 规则，配置例子如下图：\n\n![cors](demo/cors.png)\n\n### 二、计算签名\n\n由于签名计算放在前端会暴露 SecretId 和 SecretKey，我们把签名计算过程放在后端实现，前端通过 ajax 向后端获取签名结果，正式部署时请在后端加一层自己网站本身的权限检验。\n\n这里提供 [NodeJS 的签名例子](https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/)，其他语言，请参照对应的 [XML SDK](https://cloud.tencent.com/document/product/436/6474)\n\n### 三、上传例子\n\n1. 创建 test.html，填入下面的代码，修改里面的 Bucket 和 Region。\n2. 部署好后端的签名服务，并修改 getAuthorization 里的签名服务地址\n3. 把 test.html 放在 Web 服务器下，然后在浏览器访问页面，测试文件上传\n\n```html\n<input id=\"file-selector\" type=\"file\">\n<script src=\"dist/cos-js-sdk-v5.min.js\"></script>\n<script>\n  \n// 存储桶名称，由bucketname-appid 组成，appid必须填入，可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket\nconst Bucket = 'test-1250000000';\n// 存储桶Region可以在COS控制台指定存储桶的概览页查看 https://console.cloud.tencent.com/cos5/bucket/ \n// 关于地域的详情见 https://cloud.tencent.com/document/product/436/6224\nconst Region = 'ap-guangzhou';\n\n// 初始化实例，详情参考：https://cloud.tencent.com/document/product/436/11459\n\n// 1、方式一：传入临时密钥\nconst cos = new COS({\n  SecretId: 'your_tmpSecretId',\n  SecretKey: 'your_tmpSecretKey',\n  SecurityToken: 'your_sessionToken',\n});\n\n// 2、方式二：传入获取临时密钥回调\nconst cos = new COS({\n    // getAuthorization 必选参数\n    getAuthorization: function (options, callback) {\n        // 初始化时不会调用，只有调用 cos 方法（例如 cos.putObject）时才会进入\n        // 异步获取临时密钥\n        // 服务端 JS 示例：https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/\n        // 服务端其他语言参考 COS STS SDK ：https://github.com/tencentyun/qcloud-cos-sts-sdk\n        // STS 详细文档指引看：https://cloud.tencent.com/document/product/436/14048\n        const url = 'http://example.com/server/sts'; // url 替换成您自己的后端服务\n        const xhr = new XMLHttpRequest();\n        let data = null;\n        let credentials = null;\n        xhr.open('GET', url, true);\n        xhr.onload = function (e) {\n            try {\n               data = JSON.parse(e.target.responseText);\n               credentials = data.credentials;\n            } catch (e) {\n            }\n            if (!data || !credentials) {\n              return console.error('credentials invalid:\\n' + JSON.stringify(data, null, 2))\n            };\n            // 检查credentials格式\n            console.log(credentials);\n            callback({\n              TmpSecretId: credentials.tmpSecretId,\n              TmpSecretKey: credentials.tmpSecretKey,\n              SecurityToken: credentials.sessionToken,\n              // 建议返回服务器时间作为签名的开始时间，避免用户浏览器本地时间偏差过大导致签名错误\n              StartTime: data.startTime, // 时间戳，单位秒，如：1580000000\n              ExpiredTime: data.expiredTime, // 时间戳，单位秒，如：1580000000\n          });\n        };\n        xhr.send();\n    }\n});\n\n\nvar taskId;\n\n// 监听选文件\ndocument.getElementById('file-selector').onchange = function () {\n\n    var file = this.files[0];\n    if (!file) return;\n\n    // 上传文件\n    cos.uploadFile({\n        Bucket: Bucket,\n        Region: Region,\n        Key: file.name,\n        Body: file,\n        SliceSize: 1024 * 1024, // 大于1mb才进行分块上传\n        onTaskReady: function (tid) {\n          taskId = tid;\n        },\n        onProgress: function (progressData) {\n            console.log('上传中', JSON.stringify(progressData));\n        },\n    }, function (err, data) {\n        console.log(err, data);\n    });\n\n    // 可使用队列暂停、重启任务\n    // cos.pauseTask(taskId);\n\n};\n</script>\n```\n\n\n## webpack 引入方式\n\n支持 webpack 打包的场景，可以用 npm 引入作为模块\n```shell\nnpm i @acgrid/cos-js-sdk-v5 --save\n```\n\n## Start Demo\n```\n1. git clone tencent-cos-js-sdk-v5 至本地\n2. cd cos-js-sdk-v5 进入根目录后执行：npm install\n3. 修改 server 文件夹中 sts.js 或 sts.php 中的 secretId、secretKey、bucket、region 配置；注意allowPrefix和allowActions需要设置适当的权限\n4. 修改 demo/index.html 中config的Bucket、Region 参数\n5. npm run server # 用 node 启动服务\n6. 浏览器输入 http://127.0.0.1:3000/ 即可进行 demo 演示\n```\n\n## 说明文档\n\n[使用例子](demo/demo.js)\n\n[快速入门](https://cloud.tencent.com/document/product/436/11459)\n\n[接口文档](https://cloud.tencent.com/document/product/436/12260)\n","readmeFilename":"README.md","_rev":"1-da2a623212d5b54c715014fb47543187"}