🚀 在 VS Code 中！

Visual Studio Code 中的 Flask 教學

Flask 是一個輕量型 Python Web 應用程式框架，提供 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 下載；通常使用頁面上第一個出現的 Download 按鈕。
    • (Linux) 內建的 Python 3 安裝運作良好，但若要安裝其他 Python 套件，您必須在終端機中執行 sudo apt install python3-pip。
    • (macOS) 透過 macOS 上的 Homebrew 使用 brew install python3 安裝。
    • (所有作業系統) 從 Anaconda 下載 (適用於資料科學用途)。

  3. 在 Windows 上，請確定您的 Python 解譯器位置已包含在 PATH 環境變數中。您可以在命令提示字元中執行 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 中的基底頁面範本包含一組頁面的所有共用部分，包括 CSS 檔案、指令碼檔案等的參考。基底範本也會定義一或多個區塊標籤，預期擴充基底的其他範本會覆寫這些標籤。區塊標籤在基底範本和擴充範本中都以 {% 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. 將下列樣式新增至 static/site.css 中的現有「message」樣式下方，然後儲存檔案。請注意，本逐步解說並未嘗試示範回應式設計；這些樣式只會產生相當有趣的結果。

    .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 就會將該程式碼片段作為自動完成選項提供，如下一個章節所示。您也可以使用 [插入程式碼片段] 命令從選單中選擇程式碼片段。

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

使用程式碼片段新增頁面

有了程式碼片段，您可以快速為 Home、About 和 Contact 頁面建立範本。

  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>Visual Studio Code Flask 教學課程的首頁。</p>，然後儲存檔案。這些行是擴充頁面範本中唯一獨特的部分

  3. 在 templates 資料夾中，建立 about.html，使用程式碼片段插入樣板標記，在 "title" 和 "content" 區塊中分別插入 About us 和 <p>Visual Studio Code Flask 教學課程的關於頁面。</p>，然後儲存檔案。

  4. 重複上一個步驟以建立 templates/contact.html，並在兩個內容區塊中使用 Contact us 和 <p>Visual Studio Code Flask 教學課程的聯絡頁面。</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: 選取直譯器] 命令選取您選擇的環境後，執行 [終端機: 建立新的終端機] 命令 (⌃⇧` (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 和 VS Code 儲存設定和偵錯組態檔案的 .vscode 資料夾) 分開。

  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 教學課程，其中將引導您完成以下步驟：

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

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

後續步驟

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

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

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

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

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

02/06/2025