logologo
文档仓库
文档仓库
logologo
开始

概述

第一步
控制器
提供者
模块
中间件
异常过滤器
管道
守卫
拦截器
自定义装饰器

基础

自定义提供程序
异步提供者
动态模块
注入作用域
循环依赖
模块引用
懒加载模块
执行上下文
生命周期事件
发现服务
平台无关
单元测试

技术

配置
SQL
Mongo
验证
缓存
序列化
版本控制
任务调度
队列
日志
Cookies
事件
压缩
文件上传
文件流
HTTP 模块
Session
MVC
性能(Fastify)
SSE

安全

认证
授权
加密与哈希
Helmet
CORS
CSRF
速率限制

GraphQL

快速开始
解析器
变更
订阅
标量
指令
接口
联合与枚举
字段中间件
类型映射
插件
复杂度
扩展
CLI 插件
生成SDL
共享模型
其他功能
联邦

WebSocket

网关
异常过滤器
管道
守卫
拦截器
适配器

微服务

基础
Redis
MQTT
NATS
RabbitMQ
Kafka
gRPC
自定义传输
异常过滤器
管道
守卫
拦截器
部署
独立应用程序

CLI

概述
工作区
库
用法
脚本

OpenAPI

介绍
装饰器
类型映射
操作
其他特性
安全
类型与参数
CLI 插件

实用示例

REPL
CRUD生成器
SWC
Passport(认证)
热重载
MikroORM
TypeORM
Mongoose
Sequelize
路由模块
Swagger
健康检查
CQRS
Compodoc
Prisma
Sentry
静态资源
Commander
异步本地存储
Necord
套件(原Automock)

常见问题

Serverless
HTTP 适配器
长连接
全局前缀
原始请求体
混合应用
HTTPS & 多服务器
请求生命周期
错误

开发工具

概述
CI/CD
迁移指南
API参考(官方)

生态与案例

谁在用
精彩资源

支持

支持

社区

贡献者

最后更新于: 2025/11/18 02:11:37

上一页文件上传
下一页HTTP 模块

#流式文件

注意

本章展示如何从你的 HTTP 应用中流式传输文件。以下示例不适用于 GraphQL 或微服务应用。

有时你可能需要从 REST API 向客户端返回文件。在 Nest 中通常你会这样做:

@Controller('file')
export class FileController {
  @Get()
  getFile(@Res() res: Response) {
    const file = createReadStream(join(process.cwd(), 'package.json'));
    file.pipe(res);
  }
}

但这样做会导致你失去对控制器后拦截器逻辑的访问。要处理这种情况,你可以返回一个 StreamableFile 实例,框架会在底层自动处理响应流的管道传输。

#可流式传输的文件类

StreamableFile 是一个封装待返回流的类。要创建新的 StreamableFile,可以向 StreamableFile 构造函数传入 Buffer 或 Stream。

提示

StreamableFile 类可从 @nestjs/common 导入。

#跨平台支持

Fastify 默认支持直接发送文件而无需调用 stream.pipe(res),因此您完全不需要使用 StreamableFile 类。不过 Nest 在两种平台类型中都支持使用 StreamableFile,所以如果您需要在 Express 和 Fastify 之间切换,也无需担心两个引擎的兼容性问题。

#示例

您可以在下方找到一个简单示例,该示例将 package.json 作为文件而非 JSON 返回,这个思路自然可以延伸到图片、文档及其他任何文件类型。

import { Controller, Get, StreamableFile } from '@nestjs/common';
import { createReadStream } from 'fs';
import { join } from 'path';

@Controller('file')
export class FileController {
  @Get()
  getFile(): StreamableFile {
    const file = createReadStream(join(process.cwd(), 'package.json'));
    return new StreamableFile(file);
  }
}

默认的内容类型(即 HTTP 响应头 Content-Type 的值)是 application/octet-stream。如需自定义该值,您可以使用 StreamableFile 的 type 选项,或使用 res.set 方法以及 @Header() 装饰器,如下所示:

import { Controller, Get, StreamableFile, Res } from '@nestjs/common';
import { createReadStream } from 'fs';
import { join } from 'path';
import type { Response } from 'express'; // 假设我们使用的是 ExpressJS HTTP 适配器
```typescript
@Controller('file')
export class FileController {
  @Get()
  getFile(): StreamableFile {
    const file = createReadStream(join(process.cwd(), 'package.json'));
    return new StreamableFile(file, {
      type: 'application/json',
      disposition: 'attachment; filename="package.json"',
      // 如果你想将 Content-Length 值定义为文件长度以外的其他值:
      // length: 123,
    });
  }

  // 或者:
  @Get()
  getFileChangingResponseObjDirectly(
    @Res({ passthrough: true }) res: Response
  ): StreamableFile {
    const file = createReadStream(join(process.cwd(), 'package.json'));
    res.set({
      'Content-Type': 'application/json',
      'Content-Disposition': 'attachment; filename="package.json"',
    });
    return new StreamableFile(file);
  }

  // 或者:
  @Get()
  @Header('Content-Type', 'application/json')
  @Header('Content-Disposition', 'attachment; filename="package.json"')
  getFileUsingStaticValues(): StreamableFile {
    const file = createReadStream(join(process.cwd(), 'package.json'));
    return new StreamableFile(file);
  }
}