在 ASP.NET Core 中用 ImageSharp.Web 实现 URL 参数控制图像处理

在很多 Web 应用场景中，希望前端或客户端能够通过 URL 参数直接请求不同尺寸、不同格式的图片，而不是为每种尺寸都预生成一张。这种按需处理方式能节省存储、提升灵活性。使用 SixLabors 提供的 ImageSharp.Web 中间件，就可以在 ASP.NET Core 应用中轻松实现这一机制。

下面我将从集成方式、可用参数、缓存配置、安全机制、实践示例等方面展开说明。

ImageSharp.Web 中间件简介

ImageSharp.Web 是建立在 ImageSharp 基础之上的 ASP.NET Core 中间件，专用于 Web 环境下的图像请求处理。它可以：

• 拦截静态图片请求

• 从 URL 查询参数（或其他来源）读取图像处理命令

• 对原始图片进行缩放、格式转换、背景填充等操作

• 将处理结果写入缓存，以便下次快速响应

• 输出最终图像响应给客户端

使用它后，你可以像访问静态图片那样简洁地写 URL，但背后图像是动态处理的。

集成步骤：在请求管道中启用 ImageSharp.Web

下面是一个基本的集成流程，适用于 ASP.NET Core（.NET 6 / .NET 7）项目。

1. 引入 NuGet 包

dotnet add package SixLabors.ImageSharp.Web

如果你要使用更多提供器或缓存策略，也可以额外安装相关包。

2. 在服务注册中添加 ImageSharp 服务

在 Program.cs（或 Startup.cs）中，注册 ImageSharp 服务及其扩展配置：

using SixLabors.ImageSharp.Web.DependencyInjection;
using SixLabors.ImageSharp.Web.Providers;
using SixLabors.ImageSharp.Web.Processing;
using SixLabors.ImageSharp.Web.Caching;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

builder.Services.AddImageSharp(options =>
{
    // 设定浏览器缓存（Cache-Control）和服务器缓存生命周期
    options.BrowserMaxAge = TimeSpan.FromHours(1);
    options.CacheMaxAge = TimeSpan.FromDays(7);
})
.Configure<PhysicalFileSystemCacheOptions>(opt =>
{
    opt.CacheFolder = "imagesharp-cache";  // 缓存子目录（相对 wwwroot 或项目根）
})
.SetRequestParser<QueryCollectionRequestParser>()   // 使用查询字符串解析器
.AddProvider<PhysicalFileSystemProvider>()           // 从物理文件系统读取源图片
.AddProcessor<ResizeWebProcessor>()                  // 处理 width/height 等缩放命令
.AddProcessor<FormatWebProcessor>()                  // 处理 format、quality 等格式转换命令
.SetCache<PhysicalFileSystemCache>();                // 使用物理文件系统缓存

var app = builder.Build();

// 中间件顺序：UseImageSharp 必须在 UseStaticFiles 之前
app.UseImageSharp();
app.UseStaticFiles();

app.UseRouting();
app.MapDefaultControllerRoute();

app.Run();

关键要点：

• AddImageSharp(...) 用于注入基础服务与配置

• .Configure<PhysicalFileSystemCacheOptions> 设置缓存目录

• .SetRequestParser(...) 定义如何从请求中解析命令（这里用查询字符串）

• .AddProvider(...) 决定原始图片如何被读取（本地磁盘、云存储等）

• .AddProcessor(...) 注册支持的处理器（如 Resize、Format）

• .SetCache(...) 指定缓存策略与实现

• app.UseImageSharp() 必须放在 app.UseStaticFiles() 之前，以便中间件能够拦截请求

如果把 UseImageSharp 放在 UseStaticFiles 之后，就可能永远不会经过 ImageSharp.Web 中间件，因为静态文件中间件会先拦截和返回原始资源。正如社区讨论里指出：必须保证中间件顺序正确。

URL 查询参数：支持的处理命令

ImageSharp.Web 内置一组常见的处理命令，你可以在 URL 上以查询字符串形式使用它们。以下是主要命令：

• width：设置输出图片的宽度（单位像素）。若只指定一个维度，库会保持纵横比例。

• height：设置输出图片的高度。

• format：指定输出格式，如 png、jpg、webp、gif 等。

• quality：对于支持质量控制的格式（如 JPEG、WebP）设置压缩质量（一般范围 1~100）。

• rmode：指定缩放模式（如 crop、stretch、pad 等）

• rsampler：指定插值算法（如 nearest、bicubic、lanczos3 等）

• ranchor / rxy：控制缩放或裁剪时锚点（如顶、底部、中间）

• bgcolor：对于带透明通道的图片，指定背景色填充透明区

• orient / compand：用于处理 EXIF 方向、线性色彩空间等

例如：

/images/photo.jpg?width=300
/images/photo.jpg?width=300&height=200
/images/photo.jpg?format=webp&quality=80
/images/photo.jpg?width=400&format=png&bgcolor=ffffff

wwwroot/
  images/
    photo.jpg

using SixLabors.ImageSharp.Web.DependencyInjection;
using SixLabors.ImageSharp.Web.Providers;
using SixLabors.ImageSharp.Web.Processing;
using SixLabors.ImageSharp.Web.Caching;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();

// 注册 ImageSharp.Web
builder.Services.AddImageSharp(options =>
{
    options.BrowserMaxAge = TimeSpan.FromHours(1);
    options.CacheMaxAge = TimeSpan.FromDays(7);
})
.Configure<PhysicalFileSystemCacheOptions>(opt =>
{
    opt.CacheFolder = "imagesharp-cache";
})
.SetRequestParser<QueryCollectionRequestParser>()
.AddProvider<PhysicalFileSystemProvider>()
.AddProcessor<ResizeWebProcessor>()
.AddProcessor<FormatWebProcessor>()
.SetCache<PhysicalFileSystemCache>();

var app = builder.Build();

// 中间件顺序：ImageSharp 必须在 StaticFiles 之前
app.UseImageSharp();
app.UseStaticFiles();

app.UseRouting();
app.MapDefaultControllerRoute();
app.Run();