qiniu

library7.15.2jsnpmunverified

Official Node.js SDK for Qiniu Cloud Storage (Kodo) API. Current stable version is 7.15.2, released monthly. Supports bucket operations, object upload/download, CDN management, and persistent processing. Differentiators: simplified upload with token generation, resumable upload, and comprehensive integration with Qiniu's ecosystem. Ships TypeScript definitions.

storage

npm install qiniu

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QINIU

qiniu

storagejavascriptv7.15.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

qiniu

✓ import qiniu from 'qiniu'

✗ const qiniu = require('qiniu')

Default import provides the main namespace. CommonJS require also works.

auth

✓ const { auth } = require('qiniu'); // or import { auth } from 'qiniu'

Named export for authentication module. Both import styles work.

conf

✓ const { conf } = require('qiniu')

Configuration object (e.g., AccessKey/SecretKey setup). Not exported directly from ES module.

Configure Qiniu SDK with access keys, generate an upload token, and upload a file using form upload.

import qiniu from 'qiniu'; // Configure access keys const accessKey = process.env.QINIU_ACCESS_KEY ?? ''; const secretKey = process.env.QINIU_SECRET_KEY ?? ''; const options = { scope: 'my-bucket' }; // Create upload token const mac = new qiniu.auth.digest.Mac(accessKey, secretKey); const putPolicy = new qiniu.rs.PutPolicy(options); const uploadToken = putPolicy.uploadToken(mac); // Upload file const config = new qiniu.conf.Config(); config.zone = qiniu.zone.Zone_z0; const formUploader = new qiniu.form_up.FormUploader(config); const putExtra = new qiniu.form_up.PutExtra(); formUploader.putFile(uploadToken, 'mykey', './local-file.jpg', putExtra, (err, respBody, respInfo) => { if (err) throw err; console.log(respBody); });

Debug

Known issues

gotchaZone configuration must match your bucket region or uploads will fail with 400.

fix

Set config.zone to the appropriate zone: Zone_z0 (East China), Zone_z1 (North China), Zone_z2 (South China), Zone_na0 (North America), Zone_as0 (Singapore).

affects: >=0.0.0

deprecatedThe qiniu.rs.PutPolicy without custom returnBody may be deprecated in future versions.

fix

Provide returnBody in PutPolicy options to specify custom response fields.

affects: >=7.0.0

gotchaUsing require('qiniu') returns the default export, not a namespace object. You must call require('qiniu').default to get the namespace in ES6 modules.

fix

Use import qiniu from 'qiniu' or const qiniu = require('qiniu').default if using TypeScript with esModuleInterop.

affects: >=7.0.0

breakingThe qiniu.rs.GetPolicy and other old APIs have been removed in v7. Use qiniu.rs.ListPrefixOptions etc.

fix

Update to new API patterns as per v7 documentation.

affects: >=7.0.0

deprecatedThe qiniu.cdn module methods signature changed in v7.15, now require a config object for refresh/prefetch.

fix

Pass a config object with urls and direction parameters.

affects: >=7.15.0

Errors

Common errors & fixes

InvalidAccessKeyId

AccessKey or SecretKey is incorrect or not set.

fix

Check that process.env.QINIU_ACCESS_KEY and QINIU_SECRET_KEY are correctly set, or pass them directly.

400 Bad Request: bucket name is invalid

The bucket name does not exist or you don't have permission.

fix

Verify bucket name spelling and that the bucket exists in the configured zone.

Cannot find module 'qiniu'

The package is not installed or import path is wrong.

fix

Run npm install qiniu and ensure the import is 'qiniu' (not 'qiniu-sdk').

Upgrade

Version history

7.15.2latest on npm

Audit

Dependencies

formstreamrequiredMultipart form data upload for Node.js

urllibrequiredHTTP client for API requests

Agent activity

31 hits · last 30 days

node

Resources

githubgit://github.com/qiniu/nodejs-sdk ↗

packageqiniu ↗

homepagehttps://github.com/qiniu/nodejs-sdk#readme ↗