静态文件服务

相关源文件

• packages/vite/src/node/server/middlewares/static.ts
• playground/fs-serve/__tests__/base/fs-serve-base.spec.ts
• playground/fs-serve/__tests__/deny/fs-serve-deny.spec.ts
• playground/fs-serve/__tests__/fs-serve.spec.ts
• playground/fs-serve/root/src/deny/.deny
• playground/fs-serve/root/src/deny/deny.txt
• playground/fs-serve/root/src/index.html
• playground/fs-serve/root/svgVirtualModulePlugin.ts
• playground/fs-serve/root/vite.config-base.js
• playground/fs-serve/root/vite.config-deny.js
• playground/fs-serve/root/vite.config.js
• playground/optimize-missing-deps/__test__/optimize-missing-deps.spec.ts
• playground/ssr-pug/__tests__/ssr-pug.spec.ts

本文档介绍了 Vite 在开发过程中如何服务静态文件，涵盖了内置的 public 目录功能和原始文件系统访问 API。这与 资源处理 不同，后者侧重于 Vite 在构建过程中如何处理和优化图片、字体和其他媒体文件等资源。

概述

Vite 的静态文件服务系统实现了三个独立的中间件函数，它们通过不同的机制处理文件访问。

1. Public 目录：servePublicMiddleware 在服务器根目录下提供 config.publicDir（默认为 public/）中的文件。
2. 原始文件系统访问：serveRawFsMiddleware 通过 FS_PREFIX（/@fs/）提供直接的文件系统访问。
3. 项目文件：serveStaticMiddleware 从 config.root 提供静态文件。

静态文件中间件架构

来源：packages/vite/src/node/server/middlewares/static.ts79-121 packages/vite/src/node/server/middlewares/static.ts123-195 packages/vite/src/node/server/middlewares/static.ts197-235

配置选项

Public 目录

Public 目录通过 Vite 配置中的 publicDir 选项进行配置。

默认情况下，它设置为相对于项目根目录的 'public'。将其设置为 false 可禁用此功能。

文件系统服务选项

文件系统访问通过服务器配置中的 fs 选项进行配置。

来源：packages/vite/src/node/config.ts214-240

中间件实现细节

每个静态文件中间件函数都使用 sirv 库，并带有自定义的 sirvOptions 配置用于文件服务。

sirv 配置

shouldServe 函数调用 checkLoadingAccess，该函数根据文件系统安全规则返回 'allowed'、'denied' 或 'fallback'。

来源：packages/vite/src/node/server/middlewares/static.ts31-77 packages/vite/src/node/server/middlewares/static.ts286-299

servePublicMiddleware

servePublicMiddleware 函数直接在服务器根目录下提供 server.config.publicDir 中的文件，且不进行任何转换。

请求过滤逻辑

该中间件会跳过处理导入请求、内部请求（例如 /@vite-client）以及带有查询参数（如 ?url）的 URL。

来源：packages/vite/src/node/server/middlewares/static.ts79-121

serveRawFsMiddleware

serveRawFsMiddleware 函数处理以 FS_PREFIX（/@fs/）开头的请求，以提供直接的文件系统访问。

FS_PREFIX 处理

FS_PREFIX 被定义为 '/@fs/'，允许访问任何文件系统路径，但会受到 checkLoadingAccess 安全验证的约束。

来源：packages/vite/src/node/server/middlewares/static.ts197-235 packages/vite/src/node/constants.ts9

serveStaticMiddleware

serveStaticMiddleware 函数会进行别名解析和安全检查，从 server.config.root 提供静态文件。

请求处理管道

来源：packages/vite/src/node/server/middlewares/static.ts123-195

安全和访问控制

Vite 通过 checkLoadingAccess 和 isFileLoadingAllowed 函数实现文件系统访问控制。

文件访问控制流程

访问控制函数

功能	目的
isFileServingAllowed	为实现向后兼容而弃用的包装器。
isFileLoadingAllowed	核心访问控制逻辑，使用 config.server.fs 设置。
checkLoadingAccess	为文件访问返回 'allowed'、'denied' 或 'fallback'。
checkServingAccess	基于 URL 的服务请求访问控制。
respondWithAccessDenied	生成带有安全消息的 403 错误响应。

来源：packages/vite/src/node/server/middlewares/static.ts241-314 packages/vite/src/node/server/middlewares/static.ts316-332

配置示例

server.fs 配置

server.fs 配置控制着 serveRawFsMiddleware 和 serveStaticMiddleware 的文件系统访问。

属性	类型	默认	描述
strict	布尔值	true	启用文件系统访问限制。
allow	string[]	[workspaceRoot]	允许文件系统访问的目录。
deny	string[]	['.env', '.env.*', '*.{crt,pem}']	禁止访问的文件模式。

示例配置

来源：playground/fs-serve/root/vite.config.js13-24 playground/fs-serve/root/vite.config-deny.js13-18

静态文件服务与其他系统的集成

静态文件服务系统与 Vite 的其他几个系统进行了交互：

1. 模块图：在开发过程中，静态服务的文件会绕过模块图。
2. 转换管道：Public 目录中的文件会跳过转换管道。
3. 构建过程：Public 目录中的文件会直接复制到构建输出中。
4. 开发服务器：静态文件中间件是服务器中间件堆栈的核心部分。
5. HMR 系统：静态文件的更改可以触发重载，但不能触发热更新。

来源：packages/vite/src/node/server/index.ts859-917 packages/vite/src/node/server/middlewares/transform.ts106-215

常见用例

服务图片和媒体文件

将不需要处理且频繁访问的资源放入 public 目录。

public/
  ├─ favicon.ico
  ├─ logo.png
  ├─ robots.txt
  └─ fonts/
     └─ open-sans.woff2

这些文件将可以通过 `/favicon.ico`、`/logo.png` 等方式访问。

访问项目根目录以外的文件

使用 `/@fs/` 前缀来访问项目根目录以外的文件。

服务静态 HTML

将静态 HTML 文件放在项目根目录或 public 目录中。

public/
  └─ about.html  // Accessible at /about.html

来源：packages/vite/src/node/server/middlewares/static.ts59-110 packages/vite/src/node/server/middlewares/static.ts158-209

最佳实践

1. 使用 public 目录存放需要原样提供、无需处理的文件。
2. 避免将大型资源放在 public 目录中，因为它们可能受益于优化。
3. 谨慎使用 fs.strict: false，因为它会绕过安全检查。
4. 谨慎使用 /@fs/ 前缀，在可能的情况下优先从项目内部导入。
5. 在复杂的设置（如 monorepo）中，明确配置 fs.allow，而不是禁用 strict 模式。

来源： packages/vite/src/node/server/middlewares/static.ts270-418