静态文件服务器

本指南介绍在 AdonisJS 应用中提供静态文件。你将学习如何：

• 安装并配置静态文件中间件
• 理解何时使用静态文件而非编译后的资源
• 为最佳性能配置缓存、ETag 和 HTTP 请求头
• 为安全性控制对点文件的访问
• 为特定文件类型设置自定义请求头
• 将静态文件复制到生产构建中

概述

静态文件服务器让你可以直接从文件系统提供文件，而无需为每个文件创建路由处理器。这对于不需要处理的资源至关重要，如 favicon、robots.txt 文件、用户上传内容或可下载的 PDF。

如果没有静态文件服务器，你需要为想要提供的每个文件创建单独的路由。这会迅速变得难以维护：

// 没有静态中间件 —— 繁琐且容易出错
router.get('/favicon.ico', async ({ response }) => {
  return response.download('public/favicon.ico')
})
router.get('/robots.txt', async ({ response }) => {
  return response.download('public/robots.txt')
})
router.get('/images/logo.png', async ({ response }) => {
  return response.download('public/images/logo.png')
})
// ... 可能有数百个路由

有了静态中间件，public 目录中的所有文件都会自动可用。该中间件在你的路由被访问之前拦截 HTTP 请求。如果存在与请求路径匹配的文件，它会使用适当的 HTTP 请求头（用于缓存和性能）提供该文件。如果文件不存在，请求会像往常一样继续到你的路由处理器。

AdonisJS 中的关键区别：public 目录中的文件按原样提供，不进行任何处理，而 resources 目录中的文件由你的资源打包器（如 Vite）处理。将已经是最终形式的文件放在 public 中。

安装

@adonisjs/static 包已通过 web 起步套件预配置。如果你使用的是不同的起步套件，可以手动安装和配置它。

使用以下命令安装并配置该包：

node ace add @adonisjs/static

    {
      providers: [
        // ...其他 providers
        () => import('@adonisjs/static/static_provider')
      ]
    }

    server.use([
      () => import('@adonisjs/static/static_middleware')
    ])

配置

静态中间件的配置存储在 config/static.ts 文件中。

import { defineConfig } from '@adonisjs/static'

const staticServerConfig = defineConfig({
  enabled: true,
  etag: true,
  lastModified: true,
  dotFiles: 'ignore',
})

export default staticServerConfig

{
  enabled: true
}

{
  etag: true
}

{
  lastModified: true
}

{
  dotFiles: 'ignore' // 推荐
}

{
  acceptRanges: true
}

{
  cacheControl: true
}

{
  cacheControl: true,
  maxAge: '30 days'
}

{
  cacheControl: true,
  maxAge: '1 year',
  immutable: true
}

{
  headers: (path, stats) => {
    /**
     * 为 .mc2 文件设置自定义内容类型
     * 因为默认情况下它们无法被识别
     */
    if (path.endsWith('.mc2')) {
      return {
        'content-type': 'application/octet-stream'
      }
    }

    /**
     * 为 HTML 文件添加安全请求头
     * 以防止 XSS 攻击
     */
    if (path.endsWith('.html')) {
      return {
        'X-Content-Type-Options': 'nosniff',
        'X-Frame-Options': 'DENY'
      }
    }
  }
}

提供静态文件

一旦注册了中间件，你就可以在 public 目录中创建文件，并使用其文件路径在浏览器中访问它们。例如，./public/css/style.css 文件可以在 http://localhost:3333/css/style.css 访问。

以下是生产环境中典型的 public 目录的样子：

public/
├── favicon.ico           # 浏览器标签页图标
├── robots.txt           # 搜索引擎爬取指令
├── sitemap.xml          # 面向搜索引擎的 SEO 站点地图
├── images/
│   ├── logo.png         # 静态徽标（不需要优化）
│   └── og-image.jpg     # 社交媒体预览图
├── downloads/
│   ├── user-guide.pdf   # 可下载文档
│   └── terms.pdf        # 法律文档
└── uploads/
    └── avatars/         # 用户上传的头像

这些文件中的每一个都可以在其对应的 URL 访问：

• http://localhost:3333/favicon.ico
• http://localhost:3333/images/logo.png
• http://localhost:3333/downloads/user-guide.pdf

public 目录与 resources 目录

理解何时使用 public 目录与 resources 目录，对于正确组织应用的资源至关重要。

对于已经是最终形式且不需要任何处理的文件，请使用 public 目录：

• Favicon 和应用图标
• robots.txt 和 sitemap.xml 文件
• 不需要优化的静态图片（徽标、图标）
• 可下载文件（PDF、ZIP 压缩包、可执行文件）
• 你想按原样提供的第三方 JavaScript 库
• 用户上传的内容（头像、文档）

对于需要编译或优化的文件，请配合使用资源打包器的 resources 目录：

• 需要编译的 CSS/SCSS 文件
• 需要转译的现代 JavaScript/TypeScript
• 受益于优化和响应式变体的图片
• 需要版本控制或缓存清除哈希的资源
• 任何应该由 Vite 或你的构建管道处理的文件

public/styles/main.scss  # 这不会被编译
public/app.ts            # 这不会被转译

resources/css/main.scss  # 由 Vite 编译
resources/js/app.ts      # 由 Vite 转译

将静态文件复制到生产环境

当你运行 node ace build 命令时，public 目录中的文件会自动复制到 build 文件夹。这确保了你的静态文件在生产环境中与编译后的应用代码一同可用。

复制 public 文件的规则在 adonisrc.ts 文件中定义：

{
  metaFiles: [
    {
      pattern: 'public/**',
      reloadServer: false
    }
  ]
}

pattern 属性使用 glob 语法来匹配 public 目录中的所有文件。reloadServer: false 设置表示在开发期间对这些文件的更改不需要重启开发服务器。

如果你在开发服务器运行时向 public 目录添加文件，你无需重启。静态中间件会立即提供它们。但是，如果你修改了 config/static.ts 文件，你需要重启服务器以使配置更改生效。

另请参阅

• 中间件指南 - 了解更多关于 AdonisJS 中间件的工作原理
• Vite 集成 - 为 resources 目录设置资源编译
• 文件上传指南 - 处理放入 public 目录的用户上传文件