實現檔案下載功能,解決:中文檔名亂碼、瀏覽器直接開啟而非下載、大檔案記憶體溢出、斷點續傳支援、多瀏覽器 Content-Disposition 相容性。
package com.example.servlet;
import jakarta.servlet.*;
import jakarta.servlet.http.*;
import jakarta.servlet.annotation.*;
import java.io.*;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Date;
@WebServlet("/download")
public class FileDownloadServlet extends HttpServlet {
private static final int BUFFER_SIZE = 8192; // 8KB 緩衝區
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
String fileName = req.getParameter("fileName"); // 伺服器實際檔名
String showName = req.getParameter("showName"); // 下載顯示檔名
if (fileName == null || showName == null) {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "缺少參數");
return;
}
// 安全檢查:防止路徑遍歷攻擊
String baseDir = getServletContext().getRealPath("/WEB-INF/files/");
File file = new File(baseDir, fileName).getCanonicalFile();
if (!file.getAbsolutePath().startsWith(baseDir)) {
resp.sendError(HttpServletResponse.SC_FORBIDDEN, "非法路徑");
return;
}
if (!file.exists() || !file.isFile()) {
resp.sendError(HttpServletResponse.SC_NOT_FOUND, "檔案不存在");
return;
}
// 設定強制下載 MIME 類型
resp.setContentType("application/octet-stream");
resp.setHeader("Accept-Ranges", "bytes"); // 支援斷點續傳
// 處理中文檔名編碼 (核心難點)
String encodedFileName = encodeFileName(showName, req.getHeader("User-Agent"));
resp.setHeader("Content-Disposition", "attachment; filename=\"" + encodedFileName + "\"");
// 檔案大小與斷點續傳處理
long fileLength = file.length();
resp.setHeader("Content-Length", String.valueOf(fileLength));
// 處理 Range 請求 (斷點續傳)
long start = 0, end = fileLength - 1;
String rangeHeader = req.getHeader("Range");
if (rangeHeader != null && rangeHeader.startsWith("bytes=")) {
String[] ranges = rangeHeader.substring(6).split("-");
try {
start = Long.parseLong(ranges[0]);
if (ranges.length > 1 && !ranges[1].isEmpty()) {
end = Long.parseLong(ranges[1]);
}
} catch (NumberFormatException ignored) {}
resp.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT); // 206
resp.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + fileLength);
resp.setHeader("Content-Length", String.valueOf(end - start + 1));
}
// 流式傳輸 (避免大檔案 OOM)
try (FileInputStream fis = new FileInputStream(file);
BufferedInputStream bis = new BufferedInputStream(fis, BUFFER_SIZE);
ServletOutputStream sos = resp.getOutputStream()) {
bis.skip(start);
byte[] buffer = new byte[BUFFER_SIZE];
long remaining = end - start + 1;
int bytesRead;
while (remaining > 0 && (bytesRead = bis.read(buffer, 0, (int)Math.min(BUFFER_SIZE, remaining))) != -1) {
sos.write(buffer, 0, bytesRead);
remaining -= bytesRead;
}
sos.flush();
}
}
/**
* 根據 User-Agent 產生相容的 Content-Disposition filename 參數
* RFC 5987 (UTF-8'') 為標準,但舊版 IE/Edge 需特殊處理
*/
private String encodeFileName(String fileName, String userAgent) throws UnsupportedEncodingException {
String ua = (userAgent == null) ? "" : userAgent.toLowerCase();
if (ua.contains("msie") || ua.contains("trident") || ua.contains("edge")) {
// IE / 老版 Edge: URLEncoder + 空格轉 %20
return URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()).replace("+", "%20");
} else if (ua.contains("chrome")) {
// Chrome: RFC 5987 格式
return "UTF-8''" + URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()).replace("+", "%20");
} else if (ua.contains("firefox")) {
// Firefox: RFC 5987 或 ISO-8859-1 (舊版)
return "UTF-8''" + URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()).replace("+", "%20");
} else if (ua.contains("safari")) {
// Safari: ISO-8859-1 編碼 (舊版) 或 RFC 5987
return new String(fileName.getBytes(StandardCharsets.UTF_8), StandardCharsets.ISO_8859_1);
} else {
// 標準 RFC 5987
return "UTF-8''" + URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()).replace("+", "%20");
}
}
}
| 瀏覽器 | 支援格式 | 程式碼處理 |
|---|---|---|
| Chrome 現代 | RFC 5987 (UTF-8'') | "UTF-8''" + URLEncoder.encode(name, "UTF-8") |
| Firefox 現代 | RFC 5987 | 同上 |
| Safari 現代 | RFC 5987 | 同上 |
| IE / 老 Edge | URLEncoder (UTF-8) | URLEncoder.encode(name, "UTF-8").replace("+", "%20") |
| 舊版瀏覽器 | ISO-8859-1 | new String(name.getBytes("UTF-8"), "ISO-8859-1") |
Range: bytes=0-1023206 Partial ContentContent-Range: bytes 0-1023/2048, Accept-Ranges: bytesFile file = new File(baseDir, fileName).getCanonicalFile();
if (!file.getAbsolutePath().startsWith(baseDir)) {
// 拒絕存取
}
使用 getCanonicalFile() 解析符號連結與相對路徑,確保在允許目錄內。
FileInputStream → BufferedInputStream → ServletOutputStream,不載入整個檔案到記憶體<a href="/download?fileName=report_2024.pdf&showName=2024年營運報告.pdf">下載報告</a>
<!-- AJAX 觸發下載 (需 Blob 處理) -->
<script>
async function downloadFile(fileName, showName) {
const resp = await fetch(`/download?fileName=${encodeURIComponent(fileName)}&showName=${encodeURIComponent(showName)}`);
const blob = await resp.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = showName;
a.click();
URL.revokeObjectURL(url);
}
</script>
@GetMapping("/download")
public ResponseEntity download(@RequestParam String fileName,
@RequestParam String showName,
HttpServletRequest request) throws IOException {
File file = new File(baseDir, fileName);
Resource resource = new FileSystemResource(file);
String encodedName = encodeFileName(showName, request.getHeader("User-Agent"));
return ResponseEntity.ok()
.header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + encodedName + "\"")
.header(HttpHeaders.CONTENT_TYPE, "application/octet-stream")
.header(HttpHeaders.ACCEPT_RANGES, "bytes")
.contentLength(file.length())
.body(resource);
}
檔案下載看似簡單,實則涉及 **編碼相容性、串流傳輸、範圍請求、安全防護** 多個維度。本文提供的 Servlet 實作涵蓋生產環境所有關鍵點:中文檔名多瀏覽器相容、斷點續傳支援、大檔案記憶體安全、路徑遍歷防護。Spring Boot 專案可使用 ResponseEntity<Resource> 簡化實作,核心邏輯不變。