🔥 UseStaticFiles
https://learn.microsoft.com/ko-kr/aspnet/core/fundamentals/static-files?view=aspnetcore-8.0
UseStaticFiles는 ASP.NET Core 애플리케이션에서 정적 파일(Static Files)을 제공하기 위해 사용되는 미들웨어입니다.
정적 파일이란 웹 서버가 클라이언트에 그대로 전달하는 파일들로, 웹 페이지를 구성하는 데 필요한 이미지, CSS 파일, JavaScript 파일, 폰트 등을 의미합니다.
1️⃣ UseStaticFiles 미들웨어의 개념
ASP.NET Core는 기본적으로 보안을 위해 웹 루트(wwwroot 폴더) 외부의 파일에 대한 직접적인 웹 접근을 허용하지 않습니다.
UseStaticFiles 미들웨어는 이러한 제한을 해제하고, 웹 서버가 특정 디렉토리(기본값은 wwwroot)에 있는 정적 파일 요청을 처리할 수 있도록 파이프라인에 기능을 추가합니다.
이 미들웨어가 없으면, 브라우저가 /css/site.css나 /images/logo.png 같은 경로로 정적 파일을 요청했을 때, 서버는 해당 파일을 찾지 못하고 404 Not Found 오류를 반환하게 됩니다.
UseStaticFiles를 추가함으로써, ASP.NET Core 애플리케이션은 이러한 요청을 가로채어 지정된 위치에서 파일을 찾아 클라이언트에게 응답할 수 있게 됩니다.
2️⃣ UseStaticFiles의 주요 역할
- 정적 파일 서빙 활성화:
웹 루트(wwwroot)에 있는 HTML, CSS, JavaScript, 이미지 등 정적 파일을 웹 브라우저가 요청할 수 있도록 허용합니다. - 파일 경로 매핑:
들어오는 URL 요청을 서버의 실제 파일 시스템 경로에 매핑합니다. - 캐싱 헤더 추가:
효율적인 캐싱을 위해Cache-Control같은 HTTP 응답 헤더를 자동으로 추가하여 브라우저가 정적 파일을 효율적으로 캐싱하고, 다음 요청 시 서버에 다시 요청하는 대신 로컬 캐시를 사용하도록 돕습니다. - MIME 타입 추론:
파일 확장자를 기반으로 올바른 MIME 타입(Content-Type헤더)을 응답에 포함하여 브라우저가 파일을 올바르게 해석하도록 합니다. - 디렉터리 브라우징 방지:
기본적으로 보안을 위해 디렉터리 목록을 보여주지 않습니다. (이를 허용하려면 추가 설정 필요)
3️⃣ UseStaticFiles 사용 방법
UseStaticFiles 미들웨어는 보통 Program.cs 파일의 Configure 메서드에서 다른 미들웨어들과 함께 구성됩니다.
✅ 기본 사용법 (wwwroot 폴더)
가장 기본적인 사용법은 웹 루트(wwwroot) 폴더에 있는 정적 파일을 제공하는 것입니다.
이 경우, UseStaticFiles() 메서드를 인자 없이 호출하면 됩니다.
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages(); // 또는 AddControllersWithViews 등
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
// UseStaticFiles 미들웨어를 추가합니다.
// 이는 wwwroot 폴더의 정적 파일을 제공합니다.
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages(); // 또는 app.MapControllerRoute 등
app.Run();
- 위 코드에서
UseStaticFiles()를 호출하면, ASP.NET Core 프로젝트 템플릿에 기본으로 생성되는wwwroot폴더의 내용이 웹에 노출됩니다. - 예를 들어,
wwwroot/css/site.css파일이 있다면, 브라우저에서http://localhost:포트번호/css/site.css로 접근할 수 있게 됩니다.
✅ 다른 폴더의 정적 파일 제공
wwwroot 외의 다른 폴더에 있는 정적 파일을 제공하고 싶을 때는 StaticFileOptions를 구성하여 경로를 지정할 수 있습니다.
// Program.cs
var builder = WebApplication.CreateBuilder(args);
// ... 서비스 설정 ...
var app = builder.Build();
// ... 기타 미들웨어 설정 ...
// wwwroot 외의 'MyStaticFiles' 폴더에 있는 정적 파일을 제공합니다.
// URL 경로는 `/MyFiles`로 시작합니다.
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(builder.Environment.ContentRootPath, "MyStaticFiles")),
RequestPath = "/MyFiles" // URL 프리픽스
});
// 기존 wwwroot 폴더도 계속 사용하려면 이 줄도 유지합니다.
app.UseStaticFiles();
app.UseRouting();
// ... 나머지 미들웨어 및 엔드포인트 설정 ...
app.Run();
FileProvider:PhysicalFileProvider를 사용하여 서버의 실제 파일 시스템 경로를 지정합니다.ContentRootPath는 애플리케이션의 기본 디렉토리를 나타냅니다.RequestPath: 이StaticFileOptions인스턴스에 의해 제공되는 파일에 접근하기 위한 URL 프리픽스를 정의합니다.
위 예시에서는MyStaticFiles폴더에 있는image.png파일을http://localhost:포트번호/MyFiles/image.png로 접근할 수 있습니다.UseStaticFiles()를 여러 번 호출하여 여러 정적 파일 소스를 구성할 수 있습니다.
✅ 디렉터리 브라우징 활성화 (권장하지 않음)
보안상의 이유로 기본적으로 비활성화되어 있지만, 개발 목적으로 디렉터리 목록을 웹에 노출해야 하는 경우 UseDirectoryBrowser 미들웨어를 함께 사용할 수 있습니다.
// Program.cs
var builder = WebApplication.CreateBuilder(args);
// 서비스에 디렉터리 브라우징 추가
builder.Services.AddDirectoryBrowser();
var app = builder.Build();
// ... 기타 미들웨어 설정 ...
// 'MyDirectory' 폴더를 웹에 노출하고, 해당 폴더의 내용을 `/MyFolder` URL로 브라우징할 수 있도록 합니다.
app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(app.Environment.ContentRootPath, "MyDirectory")),
RequestPath = "/MyFolder"
});
// 'MyDirectory' 폴더의 정적 파일도 제공합니다.
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(app.Environment.ContentRootPath, "MyDirectory")),
RequestPath = "/MyFolder"
});
// ... 나머지 미들웨어 및 엔드포인트 설정 ...
app.Run();
- 경고:
UseDirectoryBrowser는 보안 취약점이 될 수 있으므로, 운영 환경에서는 절대 사용해서는 안 됩니다.
오직 개발/디버깅 목적으로만 제한적으로 사용해야 합니다.
4️⃣ UseStaticFiles 미들웨어의 위치
미들웨어 파이프라인에서 UseStaticFiles의 위치는 중요합니다.
- 일반적으로
UseStaticFiles는UseRouting미들웨어 앞에 위치하는 것이 좋습니다.
이렇게 하면 라우팅 시스템이 복잡한 컨트롤러/엔드포인트 매칭 로직을 시작하기 전에, 정적 파일 요청을 먼저 빠르게 처리하고 응답할 수 있어 성능에 유리합니다. - 만약
UseStaticFiles가UseRouting뒤에 오면, 정적 파일 요청도 라우팅 시스템의 대상이 되어 불필요한 처리 오버헤드가 발생할 수 있습니다. - 하지만, 특정 미들웨어(예: 인증/인가 미들웨어)를 통해 정적 파일 접근을 제어하고 싶다면, 해당 미들웨어 뒤에
UseStaticFiles를 배치할 수도 있습니다.
이 경우 정적 파일 요청도 인증/인가 절차를 거치게 됩니다.
UseStaticFiles 미들웨어는 ASP.NET Core 웹 애플리케이션에서 정적인 웹 리소스를 효율적이고 안전하게 제공하는 데 필수적인 구성 요소입니다.
