在现代 Web 应用中，针对不同设备与带宽环境按需生成合适尺寸与格式的图像，是提升性能与用户体验的重要策略。SixLabors 提供的 ImageSharp.Web 中间件，可以让你在 ASP.NET Core 应用中，通过 URL 上附加查询参数（如 ?width=200&format=png）来动态处理图像。本文将带你一步步了解如何配置、使用、优化与扩展该方案。
ImageSharp.Web 概览与原理
ImageSharp.Web 是基于 ImageSharp 图像处理库的中间件，用来在 HTTP 请求管道中截获图像请求，并在响应前根据“命令”执行变换（如缩放、裁剪、转码等）。它支持使用 URL 查询参数（或其它命令表示法）来指定处理指令。
当请求的 URL 像这样：
http://images/photo.jpg?width=300&format=png
ImageSharp.Web 会在内部解析出 width=300、format=png 等命令，加载源图像进行处理，并返回最终结果。
在其 “Processing Commands” 文档中已有对常见命令（resize、format、quality、bgcolor 等）的支持说明。
支持的 URL 参数（命令）详解
在 ImageSharp.Web 中，以下几类命令通常被用于通过 URL 控制图像处理：
-
Resize（缩放）相关参数
-
width：目标宽度（像素）。如果指定width且不指定height，则按比例缩放高度以保持纵横比。docs-v2.sixlabors.com -
height：目标高度（像素）。与width类似，只指定一边则自动等比例计算另一边。docs-v2.sixlabors.com -
rmode：调整缩放模式（如 Pad、Crop、Stretch 等） -
rsampler：指定采样器算法（如bicubic、lanczos3等） -
rxy：锚点（相对于宽高的比例位置，如0.5,0.5表示中心） -
orient、compand等：控制是否依据 EXIF 方向或开启色域扩展／压缩
-
-
Format（输出格式）
-
format：指定输出图像格式，如jpg、png、gif、webp等。
-
-
Quality（编码质量）
-
quality：适用于 JPEG / WebP 等格式，范围一般在 1–100 之间。
-
-
Background Color（背景色填充，透明图处理）
-
bgcolor：用于给带透明通道的图像指定背景色，例如bgcolor=FFFF00、bgcolor=128,64,32等。
-
这些命令的组合可以让你灵活地控制最终图像的尺寸、裁剪方式、输出格式与视觉表现。
在 ASP.NET Core 中配置 ImageSharp.Web
下面是一个基本配置示例，展示如何在 Startup 中集成 ImageSharp.Web：
public void ConfigureServices(IServiceCollection services)
{
services.AddControllersWithViews();
services.AddImageSharp() // 启用 ImageSharp 中间件
.AddWebEncoders() // 可选：编码器支持
.SetRequestParser<QueryCollectionRequestParser>() // 用 QueryString 解析命令
.Configure<PhysicalFileSystemCacheOptions>(options =>
{
options.CacheFolder = "imagesharp-cache";
})
.SetCache<PhysicalFileSystemCache>()
.SetCacheHash<CacheHash>();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// ... 其它中间件如静态文件、路由等
app.UseImageSharp(); // 插入 ImageSharp 中间件
app.UseStaticFiles(); // 静态文件中间件须在 ImageSharp 之前或之后合理排序
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
});
}
要注意几点：
-
要确保
app.UseImageSharp()在适当的位置，以便它能够截获图像请求。 -
命令解析器可以使用
QueryCollectionRequestParser，即通过查询字符串提取命令。 -
使用缓存（例如
PhysicalFileSystemCache）能显著提升性能，避免多次重复处理同一张图像。 -
可以配置
OnParseCommands、OnBeforeSave、OnProcessed等钩子，用来自定义行为。
示例：通过 URL 请求动态缩放 + 转码
假设你有一张源图 /images/sample.jpg，你希望在前端根据布局需要请求不同尺寸与格式。以下是一些可能的 URL 示例：
-
/images/sample.jpg?width=200→ 按宽度 200 缩放，高度按比例计算 -
/images/sample.jpg?width=200&height=200&rmode=Crop→ 裁剪成正方形（中心裁剪） -
/images/sample.jpg?width=300&format=webp&quality=80→ 输出 WebP 格式且质量为 80 -
/images/sample.jpg?width=300&height=200&format=png&bgcolor=FFFFFF→ 强制输出 PNG，背景设为白色（用于透明图）
在 Razor 视图中，你可以这样写：
<img src="/images/sample.jpg?width=300&format=png" alt="示例图像" />
如果启用了 HMAC 安全（可选），则生成的 URL 可能还会额外附带一个 hmac 参数，确保 URL 命令未被篡改。
缓存策略与性能优化
动态图像处理本身有一定计算开销，为了保证响应速度与资源利用，需要配合缓存策略：
-
命令结果缓存（Disk / FileSystem Cache）
在 ImageSharp.Web 中，你可以配置缓存中间件（如PhysicalFileSystemCache），将处理后的图像结果存入磁盘缓存，再次请求时直接返回缓存结果，跳过处理逻辑。 -
浏览器缓存 Header
将合理的 Cache-Control、ETag、Expires 等 Header 设置在响应上，让客户端缓存结果，减少重复请求。 -
限制请求尺寸范围
为防止恶意或非常大的尺寸请求耗尽服务器资源，可以在OnParseCommands或OnParseCommandsAsync钩子里对命令进行校验、限制最大值或拒绝异常值。 -
避免无意义放大（Upscaling）
如果请求尺寸大于原始图像尺寸，有可能导致图像模糊或耗费不必要资源。你可以在命令解析或处理阶段禁止上采样，或做尺寸校验。 -
合理选择采样器
对不同用途（缩略图 vs 高清展示图）使用不同采样器（如NearestNeighbor、Lanczos3等）。高质量的采样器通常处理较慢，可在必要时降低等级来兼顾性能。
安全性与命令验证
因为 URL 参数决定处理行为，若开放给外部用户使用，存在被滥用或篡改风险，因此推荐以下安全措施：
-
开启 HMAC 校验
在 ImageSharp.Web 中可以配置一个密钥（HMACSecretKey），让每个命令 URL 都带有一个 HMAC 校验值。如果校验失败，则拒绝处理。 -
命令白名单或黑名单
在OnParseCommands钩子中仅允许某些受控命令（如width、format），拒绝其他未知命令或过大参数。 -
尺寸限制
如前所述，对width、height等命令施加最大、最小阈值，避免极端值攻击。
高级扩展：自定义命令与处理器
ImageSharp.Web 的设计允许你注册自定义命令解析器与处理器。如果你有特殊需求，比如裁剪焦点 (focal crop)、水印、色彩滤镜等，可以：
-
实现自定义的
IRequestParser或IImageWebProcessor。 -
在中间件配置中插入你的处理器。
-
在 URL 上定义你自己的命令（如
?cropFocal=...、?watermark=logo.png等）。
这样便能打造与业务紧密结合的动态图像服务。
总结与建议
通过在 URL 上附带参数（如 ?width=200&format=png）来动态控制图像尺寸与格式，是在 ASP.NET Core 中使用 ImageSharp.Web 带来极大灵活性和性能优化的方式。要让这一方案运行稳定且安全，需要注意以下几点：
-
正确配置中间件与命令解析器
-
使用缓存（磁盘 & 浏览器）来避免重复处理
-
限制命令参数范围，防止滥用
-
必要时开启 HMAC 验证来防止 URL 被篡改
-
若有业务需求，可扩展自定义命令处理逻辑