Web 應用程序的一個常見特性是允許用戶將文件上傳到服務器。在 RFC 1867 中協議記錄了客戶端上傳文件的機制，我們最喜歡的 Web 框架 Flask 完全支持這一機制，但是對於許多開發者來說，還有許多實現細節未遵循該正式規范。諸如在何處存儲上傳的文件，如何事后使用它們，或者如何保護服務器不受惡意文件上傳的影響，這些都會產生很多混亂和不確定性。
在本文中，我將向你展示如何為 Flask 服務器實現強大的文件上傳功能，該功能不僅支持基於 Web 瀏覽器中的標准文件上傳並且與基於 JavaScript 的上傳小部件兼容：
基本文件上傳表單
從高層次的角度來看，上傳文件的客戶端與其他任何表單數據提交一樣。 換句話說，你必須定義一個包含文件字段的 HTML 表單。
下面是一個簡單的 HTML 頁面，該表單接受一個文件:
<!doctype html>
<html>
<head>
<title>File Upload</title>
</head>
<body>
<h1>File Upload</h1>
<form method="POST" action="" enctype="multipart/form-data">
<p><input type="file" name="file"></p>
<p><input type="submit" value="Submit"></p>
</form>
</body>
</html>
你可能知道，<form> 元素的 method 屬性可以是 GET 或 POST。使用 GET 時，數據將在請求 URL 的查詢字符串中提交，而使用 POST 時，數據將進入請求主體。在表單中包含文件時，必須使用 POST，因為不可能在查詢字符串中提交文件數據。
沒有文件的表單通常不包含 <form> 元素中的 enctype 屬性。此屬性定義瀏覽器在將數據提交到服務器之前應該如何格式化數據。HTML 規范為其定義了三個可能的值：
application/x-www-form-urlencoded:
這是默認格式，也是不包含文件字段的表單的最佳格式
multipart/form-data:
如果表單中至少有一個字段是文件字段，則需要此格式
text/plain:
這種格式沒有實際用途，所以你應該忽略它
實際的文件字段是我們用於大多數其他表單字段的標准 <input> 元素，其類型設置為 file。 在上面的示例中，我沒有包含任何其他屬性，但是file字段支持兩個有時有用的屬性：
multiple:
可用於允許在單個文件字段中上載多個文件。例如:
<input type="file" name="file" multiple>
accept:
可以用於篩選允許的文件類型，這些文件類型可以通過文件擴展名或媒體類型選擇。例子:
<input type="file" name="doc_file" accept=".doc,.docx">
<input type="file" name="image_file" accept="image/*">
使用 Flask 接受文件提交
對於常規表單，Flask 提供了對 request.form 字典中提交的表單字段的訪問。 但是，文件字段包含在request.files 字典中。 request.form 和 request.files 字典實際上是“multi-dicts”，它是一種支持重復鍵的專門字典實現。 這是必要的，因為表單可以包含多個具有相同名稱的字段，通常情況下是由多組復選框組成。 對於允許多個文件的文件字段，也會發生這種情況。
暫時忽略諸如驗證和安全性等重要方面，下面簡短的 Flask 應用程序接受使用上一節中定義的表單上傳的文件，並將提交的文件寫入當前目錄：
from flask import Flask, render_template, request, redirect, url_for
app = Flask(__name__)
@app.route('/')
def index():
return render_template('index.html')
@app.route('/', methods=['POST'])
def upload_file():
uploaded_file = request.files['file']
if uploaded_file.filename != '':
uploaded_file.save(uploaded_file.filename)
return redirect(url_for('index'))
upload_file() 函數使用@app.route裝飾，以便在瀏覽器發送POST請求時調用該函數。 請注意，同一個根 URL 是如何在兩個視圖函數之間進行拆分的，並將 index() 設置為接受 GET 請求，將 upload_file``() 上傳為 POST 請求。
uploaded_file 變量保存提交的文件對象。 這是 Flask 從 Werkzeug 導入的 FileStorage 類的實例。
FileStorage 中的 filename 屬性提供客戶端提交的文件名。如果用戶提交表單時沒有在 file 字段中選擇文件，那么文件名將是一個空字符串，因此始終檢查文件名以確定文件是否可用是很重要的。
Flask 收到文件提交后，不會自動將其寫入磁盤。 這實際上是一件好事，因為它使應用程序有機會查看和驗證文件提交，這一點將在后面看到。 可以從 stream 屬性訪問實際文件數據。 如果應用程序只想將文件保存到磁盤，則可以調用 save() 方法，並將所需路徑作為參數傳遞。 如果未調用文件的 save() 方法，則該文件將被丟棄。
是否要使用此應用程序測試文件上傳？ 為你的應用程序創建目錄，並將上面的代碼編寫為 app.py。 然后創建一個模板子目錄，並將上一節中的HTML頁面編寫為templates/index.html。 創建一個虛擬環境並在其上安裝Flask，然后使用 flask run 運行該應用程序。 每次提交文件時，服務器都會把它的副本寫到當前目錄中。
在繼續討論安全性主題之前，我將討論上面的代碼的一些變體，你可能會發現這些變體很有用。 如前所述，可以將文件上傳字段配置為接受多個文件。 如果像上面那樣使用 request.files['file']，則只會得到一個提交的文件，但是使用 getlist() 方法，你可以在for循環中訪問所有文件：
for uploaded_file in request.files.getlist('file'):
if uploaded_file.filename != '':
uploaded_file.save(uploaded_file.filename)
許多人在 Flask 中編寫表單處理路由時，對 GET 和 POST 請求使用單個視圖函數。使用單視圖函數的示例應用程序的版本編碼如下:
@app.route('/', methods=['GET', 'POST'])
def index():
if request.method == 'POST':
uploaded_file = request.files['file']
if uploaded_file.filename != '':
uploaded_file.save(uploaded_file.filename)
return redirect(url_for('index'))
return render_template('index.html')
最后，如果使用 Flask-WTF 擴展來處理表單，則可以使用 FileField 對象上傳文件。到目前為止，你看到的例子中使用的表單可以使用 Flask-WTF 編寫如下:
from flask_wtf import FlaskForm
from flask_wtf.file import FileField
from wtforms import SubmitField
class MyForm(FlaskForm):
file = FileField('File')
submit = SubmitField('Submit')
注意，FileField 對象來自 flask_wtf 包，與大多數其他字段類不同，后者直接從 wtforms 包導入。Flask-WTF 為文件字段提供了兩個驗證器，FileRequired 和 FileAllowed，前者執行類似於空字符串檢查的檢查，后者確保文件擴展名包含在允許的擴展名列表中。
當您使用 Flask-WTF 表單時，file 字段對象的 data 屬性指向 FileStorage 實例，因此將文件保存到磁盤的工作方式與上面的示例相同。
保護文件上傳
上一節中給出的文件上傳示例是一個非常簡單的實現，不是很健壯。Web 開發中最重要的規則之一是永遠不要信任客戶提交的數據，因此在使用常規表單時，像 Flask-WTF 這樣的擴展會在接受表單和整合數據到應用程序中之前對所有字段進行嚴格驗證。對於包含文件字段的表單，也需要進行驗證，因為如果不進行文件驗證，服務器將為攻擊敞開大門。例如:
- 攻擊者可以上傳一個非常大的文件，以至於服務器中的磁盤空間完全被填滿，從而導致服務器出現故障
- 攻擊者可以使用文件名（例如../../../.bashrc或類似文件）的上傳請求，以試圖欺騙服務器重寫系統配置文件。
- 攻擊者可以上傳帶有病毒或其他類型惡意軟件的文件到應用程序需要使用的位置，例如，用戶頭像
限制上傳文件的大小
為了防止客戶端上傳非常大的文件，您可以使用 Flask 提供的配置選項。MAX_CONTENT_LENGTH 選項控制請求主體可以擁有的最大大小。雖然這不是一個特定於文件上傳的選項，但設置一個最大的請求體大小有效地使 Flask 使用413狀態碼丟棄大於允許的請求體大小的請求
讓我們修改上一節中的 app.py 示例，只接受最大為1 MB 的請求:
app.config['MAX_CONTENT_LENGTH'] = 1024 * 1024
如果你試圖上傳一個大於1 MB 的文件，應用程序現在將拒絕它。
驗證文件名
我們不能完全相信客戶端提供的文件名是有效的和可以安全使用的，所以隨上傳文件一起提供的文件名必須經過驗證。
要執行的一個非常簡單的驗證是確保文件擴展名是應用程序願意接受的擴展名，這與使用 Flask-WTF 時F FileAllowed 驗證器所做的類似。假設應用程序接受圖像，那么它可以配置允許的文件擴展名列表:
app.config['UPLOAD_EXTENSIONS'] = ['.jpg', '.png', '.gif']
對於每個上傳的文件，應用程序可以確保文件擴展名是允許的:
filename = uploaded_file.filename
if filename != '':
file_ext = os.path.splitext(filename)[1]
if file_ext not in current_app.config['UPLOAD_EXTENSIONS']:
abort(400)
使用這種邏輯，任何不在允許的文件擴展名的文件名，都會出現400錯誤。
除了文件擴展名之外，驗證文件名以及提供的任何路徑也很重要。 如果你的應用程序不關心客戶端提供的文件名，則處理上傳的最安全方法是忽略客戶端提供的文件名，而是生成自己的文件名，然后傳遞給 save() 方法。 這種技術工作良好的示例是頭像上傳。 每個用戶的頭像都可以使用用戶 ID 保存為文件名，因此客戶端提供的文件名可以丟棄。 如果你的應用程序使用 Flask-Login，則可以實現以下 save() 調用：
uploaded_file.save(os.path.join('static/avatars', current_user.get_id()))
在其他情況下，保留客戶端提供的文件名可能更好，因此必須首先清理文件名。對於這些情況，Werkzeug 提供了 secure_filename() 函數。讓我們通過在 Python shell 中運行一些測試來看看這個函數是如何工作的:
>>> from werkzeug.utils import secure_filename
>>> secure_filename('foo.jpg')
'foo.jpg'
>>> secure_filename('/some/path/foo.jpg')
'some_path_foo.jpg'
>>> secure_filename('../../../.bashrc')
'bashrc'
正如你在示例中看到的，無論文件名有多么復雜或多么惡意，secure_filename() 函數都將其縮減為一個單位文件名。
讓我們將 secure_filename() 合並到示例上傳服務器中，並添加一個配置變量，該變量定義文件上傳的專用位置。下面是帶有安全文件名的完整 app.py 源文件:
import os
from flask import Flask, render_template, request, redirect, url_for, abort
from werkzeug.utils import secure_filename
app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 1024 * 1024
app.config['UPLOAD_EXTENSIONS'] = ['.jpg', '.png', '.gif']
app.config['UPLOAD_PATH'] = 'uploads'
@app.route('/')
def index():
return render_template('index.html')
@app.route('/', methods=['POST'])
def upload_files():
uploaded_file = request.files['file']
filename = secure_filename(uploaded_file.filename)
if filename != '':
file_ext = os.path.splitext(filename)[1]
if file_ext not in app.config['UPLOAD_EXTENSIONS']:
abort(400)
uploaded_file.save(os.path.join(app.config['UPLOAD_PATH'], filename))
return redirect(url_for('index'))
注意
secure_filename 函數將過濾所有非ASCII字符，因此，如果filename 是 "頭像.jpg"之類的，則結果為"jpg"，但沒有格式，這是個問題，我建議使用uuid模塊重命名上傳的文件，以避免出現上述情況。
驗證文件內容
我將要討論的第三層驗證是最復雜的。如果您的應用程序接受某種文件類型的上傳，那么理想情況下，它應該執行某種形式的內容驗證，並拒絕任何不同類型的文件。
如何實現內容驗證在很大程度上取決於應用程序接受的文件類型。對於本文中的示例應用程序，我使用的是圖像，因此可以使用 Python 標准庫中的 imghdr 包驗證文件頭實際上是一個圖像。
讓我們編寫一個 validate_image() 函數，對圖像執行內容驗證:
import imghdr
def validate_image(stream):
header = stream.read(512)
stream.seek(0)
format = imghdr.what(None, header)
if not format:
return None
return '.' + (format if format != 'jpeg' else 'jpg')
這個函數以一個字節流作為參數。它首先從流中讀取512個字節，然后重置流指針，因為稍后當調用 save ()函數時，我們希望它看到整個流。前512字節的圖像數據將足以識別圖像的格式。
如果第一個參數是文件名，imghdr.what() 函數可以查看存儲在磁盤上的文件; 如果第一個參數是 None，數據在第二個參數中傳遞，則可以查看存儲在內存中的數據。FileStorage 對象為我們提供了一個流，因此最方便的選項是從它中讀取安全數量的數據，並在第二個參數中將其作為字節序列傳遞。
imghdr.what() 的返回值是檢測到的圖像格式。該函數支持多種格式，其中包括流行的 jpeg、 png 和 gif。如果未檢測到已知的圖像格式，則返回值為 None。如果檢測到格式，則返回該格式的名稱。最方便的是將格式作為文件擴展名返回，因為應用程序可以確保檢測到的擴展名與文件擴展名匹配，所以 validate_image() 函數將檢測到的格式轉換為文件擴展名。這很簡單，只需為除 jpeg 外的所有圖像格式添加一個點作為前綴，jpeg 除外，通常使用 .jpg擴展名。
下面是完整的 app.py，包含前面幾節中的所有特性和內容驗證:
import imghdr
import os
from flask import Flask, render_template, request, redirect, url_for, abort
from werkzeug.utils import secure_filename
app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 1024 * 1024
app.config['UPLOAD_EXTENSIONS'] = ['.jpg', '.png', '.gif']
app.config['UPLOAD_PATH'] = 'uploads'
def validate_image(stream):
header = stream.read(512)
stream.seek(0)
format = imghdr.what(None, header)
if not format:
return None
return '.' + (format if format != 'jpeg' else 'jpg')
@app.route('/')
def index():
return render_template('index.html')
@app.route('/', methods=['POST'])
def upload_files():
uploaded_file = request.files['file']
filename = secure_filename(uploaded_file.filename)
if filename != '':
file_ext = os.path.splitext(filename)[1]
if file_ext not in app.config['UPLOAD_EXTENSIONS'] or \
file_ext != validate_image(uploaded_file.stream):
abort(400)
uploaded_file.save(os.path.join(app.config['UPLOAD_PATH'], filename))
return redirect(url_for('index'))
在視圖函數中唯一的變化就是加入了最后一個驗證邏輯:
if file_ext not in app.config['UPLOAD_EXTENSIONS'] or \
file_ext != validate_image(uploaded_file.stream):
abort(400)
這個擴展檢查首先確保文件擴展名在允許的列表中，然后確保通過查看數據流檢測到的文件擴展名與文件擴展名相同。
在測試這個版本的應用程序之前，創建一個名為 uploads 的目錄(或者你在 UPLOAD_PATH 配置變量中定義的路徑) ，以便可以將文件保存在那里。
使用上傳的文件
你現在知道如何處理文件上傳。對於某些應用程序，這就是所需要的全部內容，因為這些文件用於某些內部進程。但是對於大量的應用程序，特別是那些具有社交功能的應用程序，比如頭像，用戶上傳的文件必須與應用程序集成。以 avatar 為例，一旦用戶上傳了他們的 avatars 圖片，任何提到用戶名的地方都需要上傳的圖片顯示在側面。
我將文件上傳分為兩大類，具體取決於用戶上傳的文件是供公眾使用還是對每個用戶私有。 本文中多次討論過的 avatar 圖像顯然屬於第一類，因為這些 avatar 旨在與其他用戶公開共享。 另一方面，對上傳的圖像執行編輯操作的應用程序可能在第二類中，因為你希望每個用戶只能訪問自己的圖像。
公共文件上傳
當圖像屬於公共性質時，使圖像可供應用程序使用的最簡單方法是將上傳目錄放在應用程序的靜態文件夾中。例如，可以在 static 中創建 avatars 子目錄，然后使用用戶 id 作為名稱在該位置保存頭像。
使用 url_for() 函數以與應用程序的常規靜態文件相同的方式引用存儲在靜態文件夾的子目錄中的這些上傳文件。 我之前建議在保存上傳的頭像圖像時使用用戶 id 作為文件名。這就是圖片保存的方式:
uploaded_file.save(os.path.join('static/avatars', current_user.get_id()))
使用這個實現，給定一個用戶 id，可以生成用戶頭像的 URL 如下:
url_for('static', filename='avatars/' + str(user_id))
或者，可以將上傳保存到靜態文件夾外的目錄中，然后可以添加新的路由來為其提供服務。在示例 app.py 應用程序文件中，上傳的文件保存到 UPLOAD_PATH 配置變量中設置的位置。為了從該位置提供這些文件，我們可以實現以下路由:
from flask import send_from_directory
@app.route('/uploads/<filename>')
def upload(filename):
return send_from_directory(app.config['UPLOAD_PATH'], filename)
這個解決方案比在靜態文件夾中存儲上傳的一個優點是，在返回這些文件之前，你可以實現額外的限制，要么直接在函數體內使用 Python 邏輯，要么使用 decorator。例如，如果你只希望向登錄的用戶提供對上傳的訪問，那么你可以將 Flask-Login 的 @login_required 裝飾器添加到這個路由中，或者添加用於正常路由的任何其他身份驗證或角色檢查機制。
讓我們使用這種實現思想在示例應用程序中顯示上傳的文件。下面是 app.py 的一個新的完整版本:
import imghdr
import os
from flask import Flask, render_template, request, redirect, url_for, abort, \
send_from_directory
from werkzeug.utils import secure_filename
app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 1024 * 1024
app.config['UPLOAD_EXTENSIONS'] = ['.jpg', '.png', '.gif']
app.config['UPLOAD_PATH'] = 'uploads'
def validate_image(stream):
header = stream.read(512) # 512 bytes should be enough for a header check
stream.seek(0) # reset stream pointer
format = imghdr.what(None, header)
if not format:
return None
return '.' + (format if format != 'jpeg' else 'jpg')
@app.route('/')
def index():
files = os.listdir(app.config['UPLOAD_PATH'])
return render_template('index.html', files=files)
@app.route('/', methods=['POST'])
def upload_files():
uploaded_file = request.files['file']
filename = secure_filename(uploaded_file.filename)
if filename != '':
file_ext = os.path.splitext(filename)[1]
if file_ext not in app.config['UPLOAD_EXTENSIONS'] or \
file_ext != validate_image(uploaded_file.stream):
abort(400)
uploaded_file.save(os.path.join(app.config['UPLOAD_PATH'], filename))
return redirect(url_for('index'))
@app.route('/uploads/<filename>')
def upload(filename):
return send_from_directory(app.config['UPLOAD_PATH'], filename)
除了新的 upload() 函數之外，index() 視圖函數使用 os.listdir ()獲取上傳位置中的文件列表，並將其發送到模板以進行呈現。更新后的 _index.html _模板內容如下:
<!doctype html>
<html>
<head>
<title>File Upload</title>
</head>
<body>
<h1>File Upload</h1>
<form method="POST" action="" enctype="multipart/form-data">
<p><input type="file" name="file"></p>
<p><input type="submit" value="Submit"></p>
</form>
<hr>
{% for file in files %}
<img src="{{ url_for('upload', filename=file) }}" style="width: 64px">
{% endfor %}
</body>
</html>
有了這些改變，每次你上傳一張圖片，頁面底部就會添加一個縮略圖:
私有文件上傳
當用戶將私有文件上傳到應用程序時，需要進行額外的檢查，以防止一個用戶與未經授權的方共享文件。這些情況的解決方案需要上面所示的 upload() 視圖函數的變體，以及額外的訪問檢查。
一個常見的要求是只與所有者共享上傳的文件。當存在此需求時，存儲上傳的一種方便方法是為每個用戶使用一個單獨的目錄。例如，可以將給定用戶的上傳保存到 uploads/<user_id> 目錄，然后可以修改 uploads() 函數，使其只服務於用戶自己的上傳目錄，這樣一來，一個用戶就不可能從另一個用戶那里查看文件。下面你可以看到這個技術的一個可能的實現，再次假設使用了 Flask-Login:
@app.route('/uploads/<filename>')
@login_required
def upload(filename):
return send_from_directory(os.path.join(
app.config['UPLOAD_PATH'], current_user.get_id()), filename)
顯示上傳進度
到目前為止，我們一直依賴 web 瀏覽器提供的原生文件上傳小部件來啟動我們的文件上傳。我相信我們都同意這個小工具不是很吸引人。不僅如此，由於缺少上傳進度顯示，它無法用於上傳大文件，因為用戶在整個上傳過程中不能收到任何反饋。雖然本文的范圍是涵蓋服務器端，但我認為，如果能夠給你提供一些關於如何實現一個基於 JavaScript 的現代文件上傳小部件以顯示上傳進度的想法將很有用。
好消息是，在服務器上不需要進行任何大的更改，無論你在瀏覽器中使用哪種方法來啟動上傳，上傳機制都以相同的方式工作。 為了向你展示一個示例實現，我將用與流行的文件上傳客戶端 dropzone.js 兼容的index.html 替換HTML表單。
下面是一個新版本的 templates/index.html，它從 CDN 加載下拉區 CSS 和 JavaScript 文件，並根據dropzone documentation 實現一個上傳表單:
<html>
<head>
<title>File Upload</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/dropzone/5.7.1/min/dropzone.min.css">
</head>
<body>
<h1>File Upload</h1>
<form action="{{ url_for('upload_files') }}" class="dropzone">
</form>
<script src="https://cdnjs.cloudflare.com/ajax/libs/dropzone/5.7.1/min/dropzone.min.js"></script>
</body>
</html>
在實現 dropzone 時，我發現了一件有趣的事情，那就是它要求設置