🚀 在 VS Code 中！

Visual Studio Code 中的 Flask 教學課程

Flask 是適用於 Web 應用程式的輕量型 Python 架構，其提供 URL 路由和頁面轉譯的基本功能。

Flask 被稱為「微型」架構，因為它未直接提供表單驗證、資料庫抽象化、驗證等功能。這些功能改由稱為 Flask 擴充功能的特殊 Python 套件提供。擴充功能與 Flask 無縫整合，使其看起來像是 Flask 本身的一部分。例如，Flask 未提供頁面範本引擎，但安裝 Flask 預設會包含 Jinja 範本引擎。為了方便起見，我們通常將這些預設值視為 Flask 的一部分。

在本 Flask 教學課程中，您將建立一個簡單的 Flask 應用程式，其中包含三個使用通用基底範本的頁面。在此過程中，您將體驗 Visual Studio Code 的許多功能，包括使用終端機、編輯器、偵錯工具、程式碼片段等等。

本 Flask 教學課程的已完成程式碼專案可在 GitHub 上找到：python-sample-vscode-flask-tutorial。

如果您有任何問題，可以在 Python 擴充功能討論問答區中搜尋答案或提出問題。

先決條件

若要成功完成本 Flask 教學課程，您必須執行下列動作 (與一般 Python 教學課程中的步驟相同)

  1. 安裝 Python 擴充功能。

  2. 安裝 Python 3 的版本 (本教學課程即以此版本撰寫)。選項包括

    • (所有作業系統) 從 python.org 下載；通常使用頁面上第一個出現的 [下載] 按鈕。
    • (Linux) 內建的 Python 3 安裝運作良好，但若要安裝其他 Python 套件，您必須在終端機中執行 sudo apt install python3-pip。
    • (macOS) 透過 macOS 上的 Homebrew 使用 brew install python3 進行安裝。
    • (所有作業系統) 從 Anaconda 下載 (適用於資料科學用途)。

  3. 在 Windows 上，請確定您的 PATH 環境變數中包含 Python 解譯器的位置。您可以藉由在命令提示字元中執行 path 來檢查位置。如果未包含 Python 解譯器的資料夾，請開啟 Windows [設定]，搜尋「環境」，選取 [編輯您帳戶的環境變數]，然後編輯 [Path] 變數以包含該資料夾。

為 Flask 教學課程建立專案環境

在本節中，您將建立要在其中安裝 Flask 的虛擬環境。使用虛擬環境可避免將 Flask 安裝到全域 Python 環境中，並讓您精確控制應用程式中使用的程式庫。

  1. 在您的檔案系統上，為本教學課程建立一個資料夾，例如 hello_flask。

  2. 在 VS Code 中開啟此資料夾，方法是在終端機中導覽至該資料夾並執行 code .，或執行 VS Code 並使用 [檔案] > [開啟資料夾] 命令。

  3. 在 VS Code 中，開啟命令選擇區 ([檢視] > [命令選擇區] 或 (⇧⌘P (Windows、Linux Ctrl+Shift+P)))。然後選取 [Python: 建立環境] 命令，以在您的工作區中建立虛擬環境。選取 venv，然後選取您要用來建立虛擬環境的 Python 環境。

    注意：如果您想要手動建立環境，或在環境建立過程中遇到錯誤，請瀏覽環境頁面。

    Flask tutorial: opening the Command Palette in VS Code

  4. 在您的虛擬環境建立完成後，從命令選擇區執行終端機: 建立新終端機 (⌃⇧` (Windows、Linux Ctrl+Shift+`)))，這會建立終端機並執行其啟動指令碼，以自動啟動虛擬環境。

    注意：在 Windows 上，如果您的預設終端機類型為 PowerShell，您可能會看到錯誤訊息，指出無法執行 activate.ps1，因為系統上已停用執行指令碼。錯誤訊息中提供連結，說明如何允許指令碼。否則，請使用 [終端機: 選取預設設定檔] 將「命令提示字元」或「Git Bash」設定為預設值。

  5. 在 VS Code 終端機中執行下列命令，以在虛擬環境中安裝 Flask

    python -m pip install flask

您現在擁有一個獨立的環境，可供撰寫 Flask 程式碼。當您使用 [終端機: 建立新終端機] 時，VS Code 會自動啟動環境。如果您開啟個別的命令提示字元或終端機，請執行 source .venv/bin/activate (Linux/macOS) 或 .venv\Scripts\Activate.ps1 (Windows) 來啟動環境。當命令提示字元開頭顯示 (.venv) 時，您就知道環境已啟動。

建立並執行最簡 Flask 應用程式

  1. 在 VS Code 中，使用功能表中的 [檔案] > [新增]，按 Ctrl+N，或使用 [檔案總管] 檢視中的新增檔案圖示 (如下所示)，在專案資料夾中建立名為 app.py 的新檔案。

    Flask tutorial: new file icon in Explorer View

  2. 在 app.py 中，新增程式碼以匯入 Flask 並建立 Flask 物件的執行個體。如果您輸入下列程式碼 (而非使用複製貼上)，您可以觀察 VS Code 的 IntelliSense 和自動完成

    from flask import Flask
app = Flask(__name__)

  3. 同樣在 app.py 中，新增一個傳回內容的函式 (在此案例中為簡單字串)，並使用 Flask 的 app.route 裝飾項目，將 URL 路由 / 對應至該函式

    @app.route("/")
def home():
    return "Hello, Flask!"

    秘訣：您可以在同一個函式上使用多個裝飾項目，每行一個，視您想要對應至同一個函式的路由數目而定。

  4. 儲存 app.py 檔案 (⌘S (Windows、Linux Ctrl+S))。

  5. 在整合式終端機中，輸入 python -m flask run 來執行應用程式，這會執行 Flask 開發伺服器。開發伺服器預設會尋找 app.py。當您執行 Flask 時，您應該會看到類似下列的輸出

    (.venv) D:\py\\hello_flask>python -m flask run
 * Environment: production
   WARNING: Do not use the development server in a production environment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

    如果您看到找不到 Flask 模組的錯誤，請確定您已依照上一節結尾的說明，在虛擬環境中執行 python -m pip install flask。

    此外，如果您想要在不同的 IP 位址或連接埠上執行開發伺服器，請使用主機和連接埠命令列引數，例如 --host=0.0.0.0 --port=80。

  6. 若要開啟預設瀏覽器以顯示轉譯頁面，請在終端機中 Ctrl+按一下 http://127.0.0.1:5000/ URL。

    Flask tutorial: the running app in a browser

  7. 請注意，當您瀏覽類似 / 的 URL 時，偵錯終端機會顯示訊息，指出 HTTP 要求

    127.0.0.1 - - [11/Jul/2018 08:40:15] "GET / HTTP/1.1" 200 -

  8. 在終端機中使用 Ctrl+C 停止應用程式。

秘訣：當使用與 app.py 不同的檔案名稱 (例如 webapp.py) 時，您需要定義名為 FLASK_APP 的環境變數，並將其值設定為您選擇的檔案。Flask 開發伺服器接著會使用 FLASK_APP 的值，而非預設檔案 app.py。如需詳細資訊，請參閱Flask 命令列介面。

在偵錯工具中執行應用程式

偵錯可讓您有機會在特定程式碼行上暫停執行中的程式。當程式暫停時，您可以檢查變數、在 [偵錯主控台] 面板中執行程式碼，並利用偵錯中所述的功能。執行偵錯工具也會在偵錯工作階段開始之前自動儲存任何已修改的檔案。

開始之前：請確定您已使用 Ctrl+C 停止上一節結尾處執行的應用程式。如果您將應用程式留在某個終端機中執行，它會繼續擁有連接埠。因此，當您使用相同的連接埠在偵錯工具中執行應用程式時，原始執行中的應用程式會處理所有要求，而且您不會在偵錯中的應用程式中看到任何活動，且程式不會在中斷點停止。換句話說，如果偵錯工具似乎無法運作，請確定沒有應用程式的其他執行個體仍在執行。

  1. 將 app.py 的內容取代為下列程式碼，這會新增第二個路由和函式，讓您可以在偵錯工具中逐步執行

    import re
from datetime import datetime

from flask import Flask

app = Flask(__name__)


@app.route("/")
def home():
    return "Hello, Flask!"


@app.route("/hello/<name>")
def hello_there(name):
    now = datetime.now()
    formatted_now = now.strftime("%A, %d %B, %Y at %X")

    # Filter the name argument to letters only using regular expressions. URL arguments
    # can contain arbitrary text, so we restrict to safe characters only.
    match_object = re.match("[a-zA-Z]+", name)

    if match_object:
        clean_name = match_object.group(0)
    else:
        clean_name = "Friend"

    content = "Hello there, " + clean_name + "! It's " + formatted_now
    return content

    用於新 URL 路由 (/hello/<name>) 的裝飾項目會定義端點 /hello/，其可接受任何其他值。路由中 < 和 > 內的識別碼會定義一個變數，該變數會傳遞至函式，並可在您的程式碼中使用。

    URL 路由會區分大小寫。例如，路由 /hello/<name> 與 /Hello/<name> 不同。如果您希望相同的函式處理這兩者，請針對每個變體使用裝飾項目。

    如程式碼註解中所述，請務必篩選任意使用者提供的資訊，以避免各種應用程式攻擊。在此案例中，程式碼會篩選名稱引數，使其僅包含字母，這可避免控制字元、HTML 等的插入。(當您在下一節中使用範本時，Flask 會執行自動篩選，而您不需要此程式碼。)

  2. 在 hello_there 函式中的第一行程式碼 (now = datetime.now()) 設定中斷點，方法是執行下列任一項動作

    • 將游標放在該行上，然後按 F9，或
    • 將游標放在該行上，選取 [執行] > [切換中斷點] 功能表命令，或
    • 直接在行號左側的邊界中按一下 (將游標停留在該處時，會出現淡紅色的點)。

    中斷點會以紅色點的形式出現在左邊界中

    Flask tutorial: a breakpoint set on the first line of the hello_there function

  3. 切換至 VS Code 中的 [執行與偵錯] 檢視 (使用左側活動列或 ⇧⌘D (Windows、Linux Ctrl+Shift+D))。您可能會看到訊息「若要自訂執行與偵錯，請建立 launch.json 檔案」。這表示您尚未擁有包含偵錯組態的 launch.json 檔案。如果您按一下 [建立 launch.json 檔案] 連結，VS Code 可以為您建立該檔案

    Flask tutorial: initial view of the debug panel

  4. 選取連結，VS Code 會提示您輸入偵錯組態。從下拉式清單中選取 [Flask]，VS Code 會使用 Flask 執行組態來填入新的 launch.json 檔案。launch.json 檔案包含許多偵錯組態，每個組態都是 configuration 陣列中的個別 JSON 物件。

  5. 向下捲動並檢查組態，其名為「Python: Flask」。此組態包含 "module": "flask",，這會告知 VS Code 在啟動偵錯工具時使用 -m flask 執行 Python。它也會在 env 屬性中定義 FLASK_APP 環境變數，以識別啟動檔案，預設為 app.py，但可讓您輕鬆指定不同的檔案。如果您想要變更主機和/或連接埠，可以使用 args 陣列。

    {
    "name": "Python Debugger: Flask",
    "type": "debugpy",
    "request": "launch",
    "module": "flask",
    "env": {
        "FLASK_APP": "app.py",
        "FLASK_DEBUG": "1"
    },
    "args": [
        "run",
        "--no-debugger",
        "--no-reload"
    ],
    "jinja": true,
    "justMyCode": true
},

    注意：如果組態中的 env 項目包含 "FLASK_APP": "${workspaceFolder}/app.py"，請將其變更為 "FLASK_APP": "app.py"，如上所示。否則，您可能會遇到類似「無法匯入模組 C」的錯誤訊息，其中 C 是您的專案資料夾所在的磁碟機代號。

    注意：建立 launch.json 之後，編輯器中會顯示 [新增組態] 按鈕。該按鈕會顯示其他組態的清單，以新增至組態清單的開頭。( [執行] > [新增組態] 功能表命令會執行相同的動作。)。

  6. 儲存 launch.json (⌘S (Windows、Linux Ctrl+S))。在偵錯組態下拉式清單中，選取 [Python: Flask] 組態。

    Flask tutorial: selecting the Flask debugging configuration

  7. 選取 [執行] > [開始偵錯] 功能表命令，或選取清單旁的綠色 [開始偵錯] 箭號 (F5)，以啟動偵錯工具

    Flask tutorial: start debugging/continue arrow on the debug toolbar

    請注意，狀態列的色彩會變更以指出偵錯中

    Flask tutorial: appearance of the debugging status bar

    偵錯工具列 (如下所示) 也會出現在 VS Code 中，其中包含下列順序的命令：[暫停] (或 [繼續]，F5)、[逐步執行 (跳過)] (F10)、[逐步執行 (進入)] (F11)、[逐步執行 (跳出)] (⇧F11 (Windows、Linux Shift+F11))、[重新啟動] (⇧⌘F5 (Windows、Linux Ctrl+Shift+F5)) 和 [停止] (⇧F5 (Windows、Linux Shift+F5))。如需每個命令的描述，請參閱VS Code 偵錯。

    Flask tutorial: the VS Code debug toolbar

  8. 輸出會出現在「Python 偵錯主控台」終端機中。在該終端機中 Ctrl+按一下 http://127.0.0.1:5000/ 連結，以在瀏覽器中開啟該 URL。在瀏覽器的網址列中，瀏覽至 http://127.0.0.1:5000/hello/VSCode。在頁面轉譯之前，VS Code 會在您設定的中斷點暫停程式。中斷點上的小黃色箭號表示它是要執行的下一行程式碼。

    Flask tutorial: VS Code paused at a breakpoint

  9. 使用 [逐步執行 (跳過)] 來執行 now = datetime.now() 陳述式。

  10. 在 VS Code 視窗的左側，您會看到 [變數] 窗格，其中顯示區域變數 (例如 now) 以及引數 (例如 name)。下方是 [監看式]、[呼叫堆疊] 和 [中斷點] 的窗格 (如需詳細資訊，請參閱VS Code 偵錯)。在 [區域變數] 區段中，嘗試展開不同的值。您也可以按兩下值 (或使用 Enter (Windows、Linux F2)) 來修改它們。不過，變更變數 (例如 now) 可能會中斷程式。開發人員通常只在程式碼一開始未產生正確的值時，才會進行變更以更正值。

    Flask tutorial: local variables and arguments in VS Code during debugging

  11. 當程式暫停時，[偵錯主控台] 面板 ([終端機] 面板中的「Python 偵錯主控台」不同) 可讓您使用程式的目前狀態來實驗運算式並試用程式碼片段。例如，在您逐步執行 now = datetime.now() 行之後，您可以實驗不同的日期/時間格式。在編輯器中，選取讀取 now.strftime("%A, %d %B, %Y at %X") 的程式碼，然後按一下滑鼠右鍵並選取 [在偵錯主控台中評估]，將該程式碼傳送至偵錯主控台，並在其中執行

    now.strftime("%A, %d %B, %Y at %X")
'Wednesday, 31 October, 2018 at 18:13:39'

    秘訣：[偵錯主控台] 也會顯示應用程式內的例外狀況，這些例外狀況可能不會出現在終端機中。例如，如果您在 [執行與偵錯] 檢視的 [呼叫堆疊] 區域中看到「已在例外狀況中暫停」訊息，請切換至 [偵錯主控台] 以查看例外狀況訊息。

  12. 將該行程式碼複製到偵錯主控台底部的 > 提示字元中，並嘗試變更格式設定

    now.strftime("%a, %d %B, %Y at %X")
'Wed, 31 October, 2018 at 18:13:39'
now.strftime("%a, %d %b, %Y at %X")
'Wed, 31 Oct, 2018 at 18:13:39'
now.strftime("%a, %d %b, %y at %X")
'Wed, 31 Oct, 18 at 18:13:39'

  13. 如果您願意，可以逐步執行更多程式碼行，然後選取 [繼續] (F5) 以讓程式執行。瀏覽器視窗會顯示結果

    Flask tutorial: result of the modified program

  14. 變更程式碼中的行以使用不同的日期時間格式，例如 now.strftime("%a, %d %b, %y at %X")，然後儲存檔案。Flask 伺服器會自動重新載入，這表示變更會套用，而不需要重新啟動偵錯工具。重新整理瀏覽器上的頁面以查看更新。

  15. 完成後，關閉瀏覽器並停止偵錯工具。若要停止偵錯工具，請使用 [停止] 工具列按鈕 (紅色正方形) 或 [執行] > [停止偵錯] 命令 (⇧F5 (Windows、Linux Shift+F5))。

秘訣：若要更輕鬆地重複瀏覽至特定 URL (例如 http://127.0.0.1:5000/hello/VSCode)，請使用 print 陳述式輸出該 URL。URL 會出現在終端機中，您可以在其中使用 Ctrl+按一下 在瀏覽器中開啟它。

前往定義和查看定義命令

在您使用 Flask 或任何其他程式庫的工作期間，您可能會想要檢查這些程式庫本身的程式碼。VS Code 提供兩個方便的命令，可直接瀏覽至任何程式碼中類別和其他物件的定義

  • 前往定義會從您的程式碼跳至定義物件的程式碼。例如，在 app.py 中，在 Flask 類別 (在行 app = Flask(__name__) 中) 上按一下滑鼠右鍵，然後選取 [前往定義] (或使用 F12)，這會瀏覽至 Flask 程式庫中的類別定義。

  • 查看定義 (⌥F12 (Windows Alt+F12、Linux Ctrl+Shift+F10)，同樣位於滑鼠右鍵操作功能表中) 類似，但會直接在編輯器中顯示類別定義 (在編輯器視窗中騰出空間，以避免遮蔽任何程式碼)。按 Escape 鍵以關閉 [查看] 視窗，或使用右上角的 x。

    Flask tutorial: peek definition showing the Flask class inline

使用範本來轉譯頁面

您到目前為止在本教學課程中建立的應用程式僅從 Python 程式碼產生純文字網頁。雖然可以直接在程式碼中產生 HTML，但開發人員會避免這種做法，因為它會讓應用程式容易受到跨網站指令碼 (XSS) 攻擊。例如，在本教學課程的 hello_there 函式中，您可能會考慮使用類似 content = "<h1>Hello there, " + clean_name + "!</h1>" 的程式碼來格式化輸出，其中 content 中的結果會直接提供給瀏覽器。此開放性允許攻擊者將惡意 HTML (包括 JavaScript 程式碼) 放在 URL 中，該 URL 會在 clean_name 中結束，進而最終在瀏覽器中執行。

更好的做法是使用範本，完全將 HTML 排除在程式碼之外，讓您的程式碼僅關注資料值，而不關注轉譯。

  • 範本是 HTML 檔案，其中包含程式碼在執行階段提供的值的預留位置。範本引擎會在轉譯頁面時負責進行取代。因此，程式碼僅關注資料值，而範本僅關注標記。
  • Flask 的預設範本引擎是 Jinja，它會在您安裝 Flask 時自動安裝。此引擎提供彈性的選項，包括自動逸出 (以防止 XSS 攻擊) 和範本繼承。透過繼承，您可以定義具有通用標記的基底頁面，然後使用頁面特定的新增項目以該基底為基礎進行建置。

在本節中，您將使用範本建立單一頁面。在後續章節中，您將設定應用程式以提供靜態檔案，然後為應用程式建立多個頁面，每個頁面都包含來自基底範本的導覽列。

  1. 在 hello_flask 資料夾內，建立名為 templates 的資料夾，這是 Flask 預設尋找範本的位置。

  2. 在 templates 資料夾中，建立名為 hello_there.html 的檔案，其中包含下列內容。此範本包含兩個名為「name」和「date」的預留位置，這些預留位置以大括號組 {{ 和 }} 分隔。如您所見，您也可以直接在範本中包含格式化程式碼

    <!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>Hello, Flask</title>
    </head>
    <body>
        {%if name %}
            <strong>Hello there, {{ name }}!</strong> It's {{ date.strftime("%A, %d %B, %Y at %X") }}.
        {% else %}
            What's your name? Provide it after /hello/ in the URL.
        {% endif %}
    </body>
</html>

    秘訣：Flask 開發人員通常使用 flask-babel 擴充功能進行日期格式設定，而非 strftime，因為 flask-babel 會將地區設定和時區納入考量。

  3. 在 app.py 中，在檔案頂端附近匯入 Flask 的 render_template 函式

    from flask import render_template

  4. 同樣在 app.py 中，修改 hello_there 函式以使用 render_template 載入範本並套用具名值 (並新增路由以辨識不含名稱的情況)。render_template 假設第一個引數相對於 templates 資料夾。通常，開發人員會將範本命名為與使用它們的函式相同，但不需要相符的名稱，因為您一律在程式碼中參考確切的檔案名稱。

    @app.route("/hello/")
@app.route("/hello/<name>")
def hello_there(name = None):
    return render_template(
        "hello_there.html",
        name=name,
        date=datetime.now()
    )

    您可以看到程式碼現在簡潔許多，並且僅關注資料值，因為標記和格式設定都包含在範本中。

  5. 啟動程式 (在偵錯工具內部或外部，使用 ⌃F5 (Windows、Linux Ctrl+F5))，瀏覽至 /hello/name URL，並觀察結果。

  6. 也請嘗試使用類似 <a%20value%20that%20could%20be%20HTML> 的名稱瀏覽至 /hello/name URL，以查看 Flask 的自動逸出是否運作。 「name」值會以純文字形式顯示在瀏覽器中，而不是轉譯實際的元素。

提供靜態檔案

靜態檔案有兩種型別。第一種是樣式表之類的檔案，頁面範本可以直接參考這些檔案。這類檔案可以位於應用程式中的任何資料夾中，但通常放在 static 資料夾中。

第二種型別是您想要在程式碼中處理的檔案，例如當您想要實作傳回靜態檔案的 API 端點時。基於此目的，Flask 物件包含內建方法 send_static_file，其會產生包含在應用程式 static 資料夾中的靜態檔案的回應。

下列章節示範這兩種類型的靜態檔案。

在範本中參考靜態檔案

  1. 在 hello_flask 資料夾中，建立名為 static 的資料夾。

  2. 在 static 資料夾中，建立名為 site.css 的檔案，其中包含下列內容。輸入此程式碼之後，也請注意 VS Code 為 CSS 檔案提供的語法醒目提示，包括色彩預覽

    .message {
    font-weight: 600;
    color: blue;
}

  3. 在 templates/hello_there.html 中，在 </head> 標籤之前新增下列程式碼行，這會建立樣式表的參考。

    <link rel="stylesheet" type="text/css" href="{{ url_for('static', filename='site.css')}}" />

    此處使用的 Flask url_for 標籤會建立檔案的適當路徑。由於它可以接受變數作為引數，因此 url_for 可讓您以程式設計方式控制產生的路徑 (如果需要)。

  4. 同樣在 templates/hello_there.html 中，將 <body> 元素的內容取代為下列標記，其會使用 message 樣式而非 <strong> 標籤 (如果您只使用不含名稱的 hello/ URL，也會顯示訊息)

    {%if name %}
    <span class="message">Hello there, {{ name }}!</span> It's {{ date.strftime("%A, %d %B, %Y at %X") }}.
{% else %}
    <span class="message">What's your name? Provide it after /hello/ in the URL.</span>
{% endif %}

  5. 執行應用程式，瀏覽至 /hello/name URL，並注意訊息以藍色轉譯。完成後，停止應用程式。

從程式碼提供靜態檔案

  1. 在 static 資料夾中，建立名為 data.json 的 JSON 資料檔案，其中包含下列內容 (這是無意義的範例資料)

    {
  "01": {
    "note": "This data is very simple because we're demonstrating only the mechanism."
  }
}

  2. 在 app.py 中，新增具有路由 /api/data 的函式，其會使用 send_static_file 方法傳回靜態資料檔案

    @app.route("/api/data")
def get_data():
    return app.send_static_file("data.json")

  3. 執行應用程式並瀏覽至 /api/data 端點，以查看是否傳回靜態檔案。完成後，停止應用程式。

建立延伸基底範本的多個範本

由於大多數 Web 應用程式都有多個頁面，而且這些頁面通常共用許多通用元素，因此開發人員會將這些通用元素分隔到基底頁面範本中，然後其他頁面範本可以延伸該範本 (這也稱為範本繼承)。

此外，由於您可能會建立許多延伸相同範本的頁面，因此在 VS Code 中建立程式碼片段會很有幫助，您可以使用該程式碼片段快速初始化新的頁面範本。程式碼片段可協助您避免繁瑣且容易出錯的複製貼上作業。

下列章節逐步說明此程式的不同部分。

建立基底頁面範本和樣式

Flask 中的基底頁面範本包含一組頁面的所有共用部分，包括樣式表檔案、指令碼檔案等的參考。基底範本也會定義一或多個區塊標籤，延伸基底的其他範本預期會覆寫這些標籤。區塊標籤在基底範本和延伸範本中都以 {% block <name> %} 和 {% endblock %} 分隔。

下列步驟示範如何建立基底範本。

  1. 在 templates 資料夾中，建立名為 layout.html 的檔案，其中包含下列內容，其包含名為「title」和「content」的區塊。如您所見，標記會定義簡單的導覽列結構，其中包含首頁、關於和連絡人頁面的連結，您將在稍後的章節中建立這些頁面。每個連結再次使用 Flask 的 url_for 標籤，以在執行階段為相符的路由產生連結。

    <!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>{% block title %}{% endblock %}</title>
        <link rel="stylesheet" type="text/css" href="{{ url_for('static', filename='site.css')}}" />
    </head>

    <body>
        <div class="navbar">
            <a href="{{ url_for('home') }}" class="navbar-brand">Home</a>
            <a href="{{ url_for('about') }}" class="navbar-item">About</a>
            <a href="{{ url_for('contact') }}" class="navbar-item">Contact</a>
        </div>

        <div class="body-content">
            {% block content %}
            {% endblock %}
            <hr/>
            <footer>
                <p>&copy; 2018</p>
            </footer>
        </div>
    </body>
</html>

  2. 在現有的「message」樣式下方，將下列樣式新增至 static/site.css，然後儲存檔案。請注意，本逐步解說未嘗試示範回應式設計；這些樣式只會產生相當有趣的結果。

    .navbar {
    background-color: lightslategray;
    font-size: 1em;
    font-family: 'Trebuchet MS', 'Lucida Sans Unicode', 'Lucida Grande', 'Lucida Sans', Arial, sans-serif;
    color: white;
    padding: 8px 5px 8px 5px;
}

.navbar a {
    text-decoration: none;
    color: inherit;
}

.navbar-brand {
    font-size: 1.2em;
    font-weight: 600;
}

.navbar-item {
    font-variant: small-caps;
    margin-left: 30px;
}

.body-content {
    padding: 5px;
    font-family:'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
}

您可以在此時執行應用程式，但由於您尚未在任何位置使用基底範本，而且尚未變更任何程式碼檔案，因此結果與上一個步驟相同。完成剩餘章節以查看最終效果。

建立程式碼片段

由於您在下一節中建立的三個頁面會延伸 layout.html，因此建立程式碼片段以使用適當的基底範本參考來初始化新的範本檔案，可節省時間。程式碼片段從單一來源提供一致的程式碼片段，這可避免在使用現有程式碼複製貼上時可能發生的錯誤。

  1. 在 VS Code 中，選取 [檔案 > 喜好設定 > 設定程式碼片段]。

  2. 在出現的清單中，選取 [html]。如果您先前已建立程式碼片段，則選項可能會以清單的 [現有程式碼片段] 區段中的「html.json」形式出現。

  3. 在 VS Code 開啟 html.json 之後，在現有大括號內新增下列項目 (此處未顯示的說明註解描述詳細資料，例如 $0 行如何指出 VS Code 在插入程式碼片段後放置游標的位置)

    "Flask Tutorial: template extending layout.html": {
    "prefix": "flextlayout",
    "body": [
        "{% extends \"layout.html\" %}",
        "{% block title %}",
        "$0",
        "{% endblock %}",
        "{% block content %}",
        "{% endblock %}"
    ],

    "description": "Boilerplate template that extends layout.html"
},

  4. 儲存 html.json 檔案 (⌘S (Windows、Linux Ctrl+S))。

  5. 現在，無論何時您開始輸入程式碼片段的前置字串，例如 flext，VS Code 都會提供該程式碼片段作為自動完成選項，如下節所示。您也可以使用插入程式碼片段命令，從選單中選擇程式碼片段。

如需程式碼片段的更多一般資訊，請參閱建立程式碼片段。

使用程式碼片段來新增頁面

有了程式碼片段，您可以快速建立首頁、關於和聯絡頁面的範本。

  1. 在 templates 資料夾中，建立一個名為 home.html 的新檔案。然後開始輸入 flext，以查看程式碼片段顯示為完成選項

    Flask tutorial: autocompletion for the flextlayout code snippet

    當您選取完成選項時，程式碼片段的程式碼會出現，游標會停留在程式碼片段的插入點

    Flask tutorial: insertion of the flextlayout code snippet

  2. 在「title」區塊的插入點，寫入 Home，並在「content」區塊中，寫入 <p>Home page for the Visual Studio Code Flask tutorial.</p>，然後儲存檔案。這些行是擴充頁面範本中唯一獨特的部分

  3. 在 templates 資料夾中，建立 about.html，使用程式碼片段插入樣板標記，在「title」和「content」區塊中分別插入 About us 和 <p>About page for the Visual Studio Code Flask tutorial.</p>，然後儲存檔案。

  4. 重複上一個步驟以建立 templates/contact.html，在兩個內容區塊中使用 Contact us 和 <p>Contact page for the Visual Studio Code Flask tutorial.</p>。

  5. 在 app.py 中，為 /about/ 和 /contact/ 路徑新增函式，這些函式會參照其各自的頁面範本。同時修改 home 函式以使用 home.html 範本。

    # Replace the existing home function with the one below
@app.route("/")
def home():
    return render_template("home.html")

# New functions
@app.route("/about/")
def about():
    return render_template("about.html")

@app.route("/contact/")
def contact():
    return render_template("contact.html")

執行應用程式

在所有頁面範本都就位後，儲存 app.py、執行應用程式，並開啟瀏覽器以查看結果。在頁面之間導覽，以驗證頁面範本是否正確擴充了基礎範本。

Flask tutorial: app rendering a common nav bar from the base template

注意：如果您沒有看到最新的變更，您可能需要對頁面執行強制重新整理，以避免看到快取檔案。

選用活動

以下章節描述您在使用 Python 和 Visual Studio Code 時可能會發現有幫助的其他步驟。

為環境建立 requirements.txt 檔案

當您透過原始檔控制或其他方式共用您的應用程式程式碼時，複製虛擬環境中的所有檔案是沒有意義的，因為接收者始終可以自行重新建立環境。

因此，開發人員通常會從原始檔控制中省略虛擬環境資料夾，而是使用 requirements.txt 檔案描述應用程式的相依性。

雖然您可以手動建立檔案，但您也可以使用 pip freeze 命令，根據已在已啟動環境中安裝的確切程式庫來產生檔案

  1. 使用Python: Select Interpreter命令選取您選擇的環境後，執行Terminal: Create New Terminal命令 (⌃⇧` (Windows、Linux Ctrl+Shift+`))) 以開啟已啟動該環境的終端機。

  2. 在終端機中，執行 pip freeze > requirements.txt 以在您的專案資料夾中建立 requirements.txt 檔案。

收到專案副本的任何人 (或任何組建伺服器) 都只需要執行 pip install -r requirements.txt 命令，即可重新安裝原始環境中的套件。(但是，接收者仍然需要建立自己的虛擬環境。)

注意：pip freeze 列出您在目前環境中安裝的所有 Python 套件，包括您目前未使用的套件。此命令也會列出具有確切版本號碼的套件，您可能想要將其轉換為範圍，以便在未來具有更大的彈性。如需更多資訊，請參閱 pip 命令文件中需求檔案。

重構專案以支援進一步開發

在本 Flask 教學課程中，所有應用程式程式碼都包含在單一 app.py 檔案中。為了允許進一步開發並分離關注點，將 app.py 的各個部分重構為個別檔案會很有幫助。

  1. 在您的專案資料夾中，為應用程式建立一個資料夾，例如 hello_app，以將其檔案與其他專案層級檔案 (如 requirements.txt 和 .vscode 資料夾 (VS Code 在其中儲存設定和偵錯組態檔案)) 分開。

  2. 將 static 和 templates 資料夾移至 hello_app 中，因為這些資料夾肯定包含應用程式程式碼。

  3. 在 hello_app 資料夾中，建立一個名為 views.py 的檔案，其中包含路由和檢視函式

    from flask import Flask
from flask import render_template
from datetime import datetime
from . import app

@app.route("/")
def home():
    return render_template("home.html")

@app.route("/about/")
def about():
    return render_template("about.html")

@app.route("/contact/")
def contact():
    return render_template("contact.html")

@app.route("/hello/")
@app.route("/hello/<name>")
def hello_there(name = None):
    return render_template(
        "hello_there.html",
        name=name,
        date=datetime.now()
    )

@app.route("/api/data")
def get_data():
    return app.send_static_file("data.json")

  4. 在 hello_app 資料夾中，建立一個具有以下內容的 __init__.py 檔案

    import flask
app = flask.Flask(__name__)

  5. 在 hello_app 資料夾中，建立一個具有以下內容的 webapp.py 檔案

    # Entry point for the application.
from . import app    # For application discovery by the 'flask' command.
from . import views  # For import side-effects of setting up routes.

  6. 開啟偵錯組態檔案 launch.json 並更新 env 屬性如下，以指向啟動物件

    "env": {
    "FLASK_APP": "hello_app.webapp"
},

  7. 刪除專案根目錄中原始的 app.py 檔案，因為其內容已移至其他應用程式檔案中。

  8. 您的專案結構現在應與以下類似

    Flask tutorial: modified project structure with separate files and folders for parts of the app

  9. 再次在偵錯工具中執行應用程式，以確保一切正常運作。若要在 VS Code 偵錯工具外部執行應用程式，請使用終端機中的以下步驟

    1. 為 FLASK_APP 設定環境變數。在 Linux 和 macOS 上，使用 export set FLASK_APP=webapp；在 Windows 上，如果您使用 PowerShell，請使用 $env:FLASK_APP=webapp，如果您使用命令提示字元，請使用 set FLASK_APP=webapp。
    2. 導覽至 hello_app 資料夾，然後使用 python -m flask run 啟動程式。

使用 Docker 擴充功能為 Flask 應用程式建立容器

Docker 擴充功能讓您可以輕鬆地從 Visual Studio Code 建置、管理和部署容器化應用程式。如果您有興趣瞭解如何為本教學課程中開發的 Flask 應用程式建立 Python 容器，請查看容器中的 Python教學課程，其中將逐步引導您如何

  • 建立描述簡單 Python 容器的 Dockerfile 檔案。
  • 建置、執行和驗證 Flask 應用程式的功能。
  • 偵錯在容器中執行的應用程式。

如果您有任何問題，可以在 Python 擴充功能討論問答區中搜尋答案或提出問題。

後續步驟

恭喜您完成本 Visual Studio Code 中使用 Flask 的逐步解說！

本教學課程的已完成程式碼專案可在 GitHub 上找到：python-sample-vscode-flask-tutorial。

由於本教學課程僅觸及頁面範本的表面，如需有關範本的更多資訊，請參閱 Jinja2 文件。範本設計工具文件包含有關範本語言的所有詳細資訊。您可能也想查看 官方 Flask 教學課程以及 Flask 擴充功能的文件。

若要在生產網站上試用您的應用程式，請查看教學課程 使用 Docker 容器將 Python 應用程式部署到 Azure App Service。Azure 也提供標準容器，Linux 上的 App Service，您可以從 VS Code 將 Web 應用程式部署到該容器。

您可能也想查看 VS Code 文件中與 Python 相關的下列文章

04/03/2025