用 HTTP 做檔案下載其實很單純:伺服器設定好回應標頭,再以二進位方式傳輸檔案內容,瀏覽器就會依標頭決定怎麼處理。在 Node.js 中,讀取檔案串流後用 .pipe() 接到回應物件 Response 上,一個可用的下載服務就完成了。
HTTP 靠請求標頭與回應標頭進行狀態交互。客戶端收到伺服器的正確狀態後,會先解析回應標頭,再據此接收並展示資料。下載流程因此是:
Content-Type、Content-Disposition 等標頭,分別表示檔案的 MIME 類型與檔案描述。Content-Type: application/octet-stream Content-Disposition: attachment; filename=MyFileName.ext
application/octet-stream 告訴瀏覽器這是一個二進位檔案;Content-Disposition 則告訴瀏覽器這是要下載的附件,並指定預設檔名。少了後者,瀏覽器可能直接顯示內容而非下載,且各家行為不一。
以下以 Express 為例,實作兩個功能:瀏覽伺服器檔案與下載檔案。
router.get('/files', function (req, res, next) {
// 顯示伺服器檔案
});
router.get('/file/:fileName', function (req, res, next) {
// 實作檔案下載
});
需要用到 fs 讀取目錄、path 處理路徑:
const fs = require('fs');
const path = require('path');
router.get('/files', function (req, res, next) {
var filePath = path.join(__dirname, './');
fs.readdir(filePath, function (err, results) {
if (err) throw err;
if (results.length > 0) {
var files = [];
results.forEach(function (file) {
if (fs.statSync(path.join(filePath, file)).isFile()) {
files.push(file);
}
});
res.render('files', { files: files });
} else {
res.end('當前目錄下沒有檔案');
}
});
});
搭配的視圖 files.ejs:
<!DOCTYPE html>
<html>
<head><title>選擇下載檔案</title></head>
<body>
<h1>請選擇要下載的檔案:</h1>
<% if (files.length > 0) { %>
<ul>
<% files.forEach(function (file) { %>
<li><a href="/file/<%- file %>" target="_blank"><%- file %></a></li>
<% }) %>
</ul>
<% } else { %>
<p>沒有可下載的檔案…</p>
<% } %>
</body>
</html>
實作有兩條路:把檔案讀進 Buffer 後用 res.send() 送出,或基於串流(Stream)處理。串流方式更適合大檔案——fs.createReadStream() 建立可讀流,而回應物件本身就是可寫流,用 .pipe() 接起來即可,不必等整個檔案進記憶體。
router.get('/file/:fileName', function (req, res, next) {
var fileName = req.params.fileName;
var filePath = path.join(__dirname, fileName);
var stats = fs.statSync(filePath);
if (stats.isFile()) {
res.set({
'Content-Type': 'application/octet-stream',
'Content-Disposition': 'attachment; filename=' + fileName,
'Content-Length': stats.size
});
fs.createReadStream(filePath).pipe(res);
} else {
res.end(404);
}
});
補上 Content-Length 除了讓瀏覽器能顯示下載進度,也能及早發現傳輸是否完整。
上面的範例直接把網址參數拼進檔案路徑,這存在路徑穿越(Path Traversal)風險:請求 /file/../../etc/passwd 就可能讀到伺服器上的任意檔案。正式環境至少要加上三層防護:
const safePath = path.normalize(path.join(__dirname, fileName));
if (!safePath.startsWith(__dirname)) {
return res.status(403).end('Forbidden');
}
除此之外,建議只允許下載白名單目錄內的檔案、對檔名做正則驗證(例如僅允許 ^[\w\-\u4e00-\u9fa5]+\.\w{1,5}$),並在串流過程中掛上 error 事件處理,避免檔案中途被刪除時造成未捕獲例外。