@getlarge/nestjs-tools-file-storage

中文文档
1.4.3发布于 2026/04/08Apache-2.0TypeScriptCommonJS近 30 天下载 6928

File Storage Juggler

原始使用文档
文档目录6 节
  1. Installation
  2. Example
  3. Testing
  4. AWS
  5. Google Cloud
  6. Troubleshooting

File-storage

npm

This module provide a unified API to store files in different storage providers.

Supoorted backends:

Installation

npm install --save @getlarge/nestjs-tools-file-storage

Example

// module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { FileStorageLocal, FileStorageModule, FileStorageS3 } from '@getlarge/nestjs-tools-file-storage';

import { AppService } from './env';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    FileStorageModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (configService: ConfigService) => {
        const environment = configService.get('NODE_ENV', { infer: true });
        if (environment === 'development') {
          const setup = {
            storagePath: configService.get('STORAGE_PATH'),
            maxPayloadSize: configService.get('MAX_PAYLOAD_SIZE'),
          };
          return new FileStorageLocal(setup);
        }
        const setup = {
          maxPayloadSize: configService.get('MAX_PAYLOAD_SIZE'),
          bucket: configService.get('AWS_S3_BUCKET'),
          region: configService.get('AWS_S3_REGION'),
          credentials: {
            accessKeyId: configService.get('AWS_S3_ACCESS_KEY_ID'),
            secretAccessKey: configService.get('AWS_S3_SECRET_ACCESS_KEY'),
          },
        };
        return new FileStorageS3(setup);
      },
    }),
  ],
  providers: [AppService],
})
export class AppModule {}
// service.ts
import { FileStorageService } from '@getlarge/nestjs-tools-file-storage';
import { Inject, Injectable, Logger } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class AppService {
  constructor(
    @Inject(ConfigService) private readonly configService: ConfigService,
    @Inject(FileStorageService)
    private readonly fileStorageService: FileStorageService,
  ) {}

  getFile(filePath: string): Promise<Buffer> {
    return this.fileStorage.downloadFile({ filePath });
  }

  setFile(filePath: string, content: string): Promise<void> {
    return this.fileStorage.uploadFile({
      filePath,
      content,
    });
  }

  deleteFile(filePath: string): Promise<void> {
    return this.fileStorage.deleteFile({ filePath });
  }
}

Testing

To run the tests, you need to have a .env.test file in the root of the project following the structure of the .env.test.sample file. You should also authenticate to external services.

AWS

I highly recommend configuring the AWS Identity Center to manage your AWS credentials for development.

Note: You can use the aws CLI to authenticate, find more information here.

Once authenticated:

  • set the AWS_PROFILE environment variable to the profile you want to use
  • or set the AWS_S3_ACCESS_KEY_ID and AWS_S3_SECRET_ACCESS_KEY environment variables.

Google Cloud

The recommended approach is to setup Application Default Credentials.

Note: You can use the gcloud CLI to authenticate, more information here.

Troubleshooting

If, after upgrading, you get the following error:

/usr/local/bin/node[57897]: ../src/node_http_parser.cc:517:static void node::(anonymous namespace)::Parser::Execute(const FunctionCallbackInfo<v8::Value> &): Assertion `parser->current_buffer_.IsEmpty()' failed.

You need to update to node v18.6 or higher. This is due to an issue with the node http module. More information can be found here and here.

版本与发布记录

@getlarge/nestjs-tools-file-storage 共发布 8 个版本,首次发布于 2024/04/17;过去 12 个月发布了 1 个版本。

版本发布日期距今
1.4.3latest2026/04/087 个月前
1.4.22025/01/311.8 年前
1.4.12024/09/142 年前
1.4.02024/08/072 年前
1.3.02024/08/032 年前
1.2.02024/08/022 年前

关于 @getlarge/nestjs-tools-file-storage 的常见问题

@getlarge/nestjs-tools-file-storage 是什么?

File Storage Juggler

如何安装 @getlarge/nestjs-tools-file-storage?

在项目目录运行 npm install @getlarge/nestjs-tools-file-storage,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@nestjs/common(^10 || ^11)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@getlarge/nestjs-tools-file-storage 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getlarge/nestjs-tools-file-storage 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@getlarge/nestjs-tools-file-storage 可以商用吗?

@getlarge/nestjs-tools-file-storage 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@getlarge/nestjs-tools-file-storage 的下载量有多少?

根据 npm 官方下载统计,@getlarge/nestjs-tools-file-storage 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,928 次,日均约 231 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getlarge/nestjs-tools-file-storage 还在维护吗?

最新版本 1.4.3 发布于 2026/04/08(7 个月前);至今共发布 8 个版本,其中过去 12 个月发布了 1 个;首次发布于 2024/04/17。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。