# strapi-provider-upload-oss

> Aliyun OSS provider for strapi upload

Latest version **0.2.3** (published 2026-06-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install strapi-provider-upload-oss
pnpm add strapi-provider-upload-oss
yarn add strapi-provider-upload-oss
bun add strapi-provider-upload-oss
```

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2026-06-07 |
| First published | 2018-12-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 10.0.0 |
| Dependencies | 1 |
| Unpacked size | 8.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 67 |
| Author | hezzze |
| Maintainers | hezzze |
| Keywords | upload, aliyun, oss, strapi |

## Links

- npm: https://www.npmjs.com/package/strapi-provider-upload-oss
- Repository: https://github.com/hezzze/strapi-provider-upload-oss
- Homepage: http://strapi.io
- Issues: https://github.com/hezzze/strapi-provider-upload-oss/issues
- npm.io page: https://npm.io/package/strapi-provider-upload-oss

## Dependencies (1)

- [ali-oss](https://npm.io/package/ali-oss.md) ^6.0.1

## Recent versions

- 0.2.3 (latest) — 2026-06-07
- 0.0.2-beta.1 (beta) — 2018-12-06
- 0.0.1-alpha.2 (alpha) — 2018-12-04
- 0.2.1 — 2024-07-24
- 0.2.0 — 2023-10-07
- 0.1.7 — 2022-07-07
- 0.1.6 — 2021-06-21
- 0.1.5 — 2020-07-03
- 0.1.4 — 2020-07-02
- 0.1.3 — 2020-06-11
- 0.1.2 — 2020-02-17
- 0.1.1 — 2019-10-11
- 0.1.0 — 2019-10-07
- 0.0.4 — 2019-01-24
- 0.0.3 — 2018-12-06
- … 3 more at https://npm.io/package/strapi-provider-upload-oss/versions

## README

# strapi-provider-upload-oss
A provider for strapi server to upload file to Aliyun OSS.

# Requirements
- Node.js >= 10
- npm > 6

# Installation
```bash
$ npm install strapi-provider-upload-oss --save
```

or

```bash
$ yarn add strapi-provider-upload-oss --save
```

For more details, please see: https://strapi.io/documentation/developer-docs/latest/development/plugins/upload.html#using-a-provider

# Usage


### Strapi v4

The lastest version of the provider supports v4 by default, configuration is updated a little bit. See example below for ```./config/plugins.js```:

```javascript
module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: 'strapi-provider-upload-oss', // full package name is required
      providerOptions: {
        accessKeyId: env('ACCESS_KEY_ID'),  // required
        accessKeySecret: env('ACCESS_KEY_SECRET'), // required
        region: env('REGION'), // required
        bucket: env('BUCKET'), // required
        uploadPath: env('UPLOAD_PATH'),
        baseUrl: env('BASE_URL'),
        timeout: env('TIMEOUT'),
        secure: env('OSS_SECURE'),
        internal: env.bool('OSS_INTERNAL', false),
        bucketParams: {
          ACL: 'private', // default is 'public-read'
          signedUrlExpires: 60 * 60 // default is 30 * 60 (30min)
        }
      }
    }
  }
});
```

Official documentation [here](https://docs.strapi.io/developer-docs/latest/plugins/upload.html#enabling-the-provider)

### Strapi v3

With a stable release of Strapi 3.0.0, the configuration was moved to a JavaScript file. Official documentation [here](https://docs-v3.strapi.io/developer-docs/latest/development/plugins/upload.html#enabling-the-provider).

To enable the provider, create or edit the file at ```./config/plugins.js```.

```javascript
module.exports = ({ env }) => ({
  upload: {
    provider: 'oss',
    providerOptions: {
      accessKeyId: env('ACCESS_KEY_ID'),
      accessKeySecret: env('ACCESS_KEY_SECRET'),
      region: env('REGION'),
      bucket: env('BUCKET'),
      uploadPath: env('UPLOAD_PATH'),
      baseUrl: env('BASE_URL'),
      timeout: env('TIMEOUT'),
      secure: env('OSS_SECURE'), //default to true
      internal: env.bool('OSS_INTERNAL', false),
    }
  }
});
```

### Provider Options

Property | type |  value
----- | ---- | ------------
**accessKeyId** | string | <aliyun access key id>
**accessKeySecret** | string | <aliyun access key secret>
**region** | string | OSS region (see reference below)
**bucket** | string | bucket name
**uploadPath** | string | path to store the file
**baseUrl** | string | can be your custom oss url for accessing the uploaded file, e.g. //www.website.com
**timeout** | integer | OSS upload timeout (unit: seconds)
**secure** | boolean | will https mode be enabled for oss client
**internal** | boolean | access OSS with aliyun internal network or not, default is false. If your servers are running on aliyun too, you can set true to save lot of money.


# OSS Region reference
https://help.aliyun.com/document_detail/31837.html#title-qvx-r3a-xr4

# Troubleshooting

Q: getting "The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint."

A: Check if the OSS region is correct for the bucket you're using

# Contribution
This repo is maintained periodically, any contribution is highly welcomed

---
_Source: https://npm.io/package/strapi-provider-upload-oss · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._