用Python Flask搭建第一个网页应用详细教程

程一诺
程一诺
发布时间:2026-11-22| 6人浏览过
原创

本教程详细讲解如何使用Python微型Web框架Flask从零搭建第一个网页应用,涵盖虚拟环境配置、最小实例编写、路由与参数传递、Jinja2模板渲染以及常见报错排查。

本文将引导你在本地环境中从零开始搭建并运行一个基于 Python Flask 的网页应用。我们将按部就班地完成独立虚拟环境准备、最小服务脚本编写、路由与动态传参设置、Jinja2 模板渲染以及开发调试验证,最终实现一个具备完整页面结构与数据交互能力的本地 Web 应用。

一、认识 Flask 及其工作运行机制

Flask 是一个基于 Python 编写的轻量级 Web 开发框架,在行业内常被称为“微框架”(Microframework)。所谓的“微”并非指其功能残缺或仅能开发小型项目,而是指它保持了核心的精简:Flask 核心仅专注处理 HTTP 请求分发(WSGI 协议实现)与基础模板渲染,其余如数据库操作、表单校验、用户认证等功能均通过可插拔的扩展库按需引入。

理解 Flask 运行的第一步是搞清楚 Web 请求的处理周期。当你在浏览器地址栏输入网址并按下回车,浏览器向服务器发起 HTTP 请求;Flask 接收到请求后,依据开发者预先定义的“路由规则”(URL 路径)匹配到对应的 Python“视图函数”;视图函数执行业务逻辑后,将渲染好的 HTML 页面或 JSON 数据包装为 HTTP 响应返回给浏览器呈现。

用Python Flask搭建第一个网页应用详细教程
图 1:Flask 客户端请求-路由分发-视图处理-响应返回架构全景

二、实操步骤概览与环境准备

为了避免全局 Python 环境中包版本冲突,开发 Python 项目的行业标准是为每个项目建立一个专属的虚拟环境(Virtual Environment)。通过这种方式,项目安装的所有依赖库均限制在该项目文件夹内部,既便于版本管理,也避免污染操作系统预装的 Python 环境。

搭建一个标准的 Flask 项目通常包含五个明确的操作阶段。在执行具体命令前,我们先通过操作流程图明确每一步的目标。

用Python Flask搭建第一个网页应用详细教程
图 2:从项目初始化到运行验证的 5 步实操全景流程图

1. 创建工作目录与虚拟环境

打开终端(macOS/Linux 使用 Terminal,Windows 推荐使用 PowerShell 或 CMD),执行以下命令创建并进入项目专用文件夹:

终端命令
# 创建项目目录并进入
mkdir my_flask_app
cd my_flask_app

# 使用 Python 内置的 venv 模块创建名为 .venv 的虚拟环境
python3 -m venv .venv

2. 激活虚拟环境并安装 Flask

虚拟环境创建完成后必须激活。激活后,终端提示符前通常会出现 (.venv) 标识,表示后续执行的 python/pip 命令均运行在该隔离环境中:

macOS / Linux 激活命令
source .venv/bin/activate
Windows PowerShell 激活命令
.venv\Scripts\Activate.ps1

激活之后,使用 pip 工具直接下载安装 Flask:

终端命令
pip install Flask

安装完成后,可以通过执行 flask --version 验证安装是否成功。

三、编写第一个最小 Flask 应用程序

在项目根目录(my_flask_app)中新建一个名为 app.py 的文件。这是 Flask 应用的核心入口脚本。

重要注意事项:切勿将你的代码文件命名为 flask.py!如果命名为 flask.py,在 Python 执行 import flask 时会优先导入该本地文件本身,导致循环导入并抛出 AttributeError 错误。

在 app.py 中录入以下完整代码:

app.py
from flask import Flask

# 1. 实例化 Flask 对象,传入 __name__ 作为定位根目录的基准
app = Flask(__name__)

# 2. 使用装饰器定义路由与绑定的视图函数
@app.route("/")
def index():
    # 3. 视图函数的返回值即为返回给浏览器的响应主体
    return "

欢迎访问我的第一个 Flask 网页应用!

服务器已成功启动并正常响应请求。

" # 4. 支持脚本直接启动 if __name__ == "__main__": app.run(debug=True)

核心代码逐行剖析

  • app = Flask(__name__):这里的 __name__ 是 Python 内置变量,代表当前模块的名称。Flask 需要依据这个参数来确定应用程序所在的根路径,以便后续准确定位静态资源文件(static)和页面模板(templates)。
  • @app.route("/"):这是一个路由装饰器,作用是把 URL 路径 /(根路由)与紧随其后的函数 index() 绑定在一起。当用户访问根路径时,Flask 自动触发该函数。
  • return "...":Flask 允许视图函数直接返回字符串。Flask 内部会将其自动封装为 MIME 类型为 text/html; charset=utf-8 的标准 HTTP 响应报文。
  • app.run(debug=True):开启 Debug 调试模式。在调试模式下,如果修改并保存代码,本地服务器会自动热重启;若代码运行抛出异常,浏览器端将直接显示交互式报错回溯,极大提升排查效率。

四、启动本地服务器并检验访问

运行 Flask 应用有两种常用方式:一种是直接使用 Python 解释器执行脚本,另一种是使用 Flask 命令行工具。在终端中执行以下命令之一:

终端命令
# 方式一:直接运行脚本
python app.py

# 方式二:使用 Flask 官方 CLI 工具(推荐)
flask --app app run --debug

终端成功启动后,将输出类似如下的信息:

终端输出示例
 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 123-456-789

此时打开电脑中的任何现代浏览器,在地址栏输入 http://127.0.0.1:5000 或 http://localhost:5000,即可在屏幕上看到我们返回的 HTML 标题与正文。终端同时会打印出一行类似 "GET / HTTP/1.1" 200 - 的访问日志,确认 200 成功状态码。

五、进阶:动态路由与参数传递

实际的 Web 应用不仅仅只有固定页面,往往需要根据用户的输入或 URL 参数动态展示不同内容(如个人主页 /user/alice 或文章页 /post/101)。Flask 提供了极其直观的动态路由参数语法。

在 app.py 中追加以下两个视图函数:

app.py 追加代码
# 动态字符串参数
@app.route("/user/<username>")
def show_user_profile(username):
    # URL 中的 <username> 会被自动提取并作为实参传入函数
    return f"

当前正在访问用户【{username}】的个人空间

" # 带有类型转换器的数字参数 @app.route("/post/<int:post_id>") def show_post(post_id): # int: 保证只有纯数字路径会匹配,且 post_id 自动转为整型 return f"

当前阅读的文章编号为:第 {post_id} 篇

"

保存文件后,由于开启了 debug 模式,服务器会自动热重载。此时分别访问 http://127.0.0.1:5000/user/developer 与 http://127.0.0.1:5000/post/42,页面将动态显示提取出的参数值;若访问 http://127.0.0.1:5000/post/abc,由于不满足 int 类型约束,Flask 会自动返回标准的 404 Not Found 响应。

六、前后端解耦:Jinja2 模板与静态资源

直接在 Python 脚本中硬编码长串 HTML 字符串不利于排版维护与复杂交互。现代 Web 开发强调“表现层”与“逻辑层”分离。Flask 默认集成了强大的 Jinja2 模板引擎,允许我们将 HTML 页面存放在外部模板文件中,并在渲染时将 Python 变量动态注入其中。

要使用模板和样式表,项目必须遵循 Flask 的预设目录结构:

用Python Flask搭建第一个网页应用详细教程
图 3:Flask 约定目录层级与 Jinja2 模板数据合并流转机制

1. 创建模板目录与 HTML 页面

在项目根目录下创建 templates 文件夹,并在其中新建 index.html:

templates/index.html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>{{ title }}</title>
  <!-- 动态加载 static 目录下的样式表 -->
  <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
</head>
<body>
  <div class="container">
    <h1>你好,{{ user }}!</h1>
    <p>这是由 Flask 配合 Jinja2 引擎渲染出的动态网页。</p>
    <h3>当前学习清单:</h3>
    <ul>
      {% for item in tasks %}
        <li>{{ item }}</li>
      {% endfor %}
    </ul>
  </div>
</body>
</html>

2. 创建静态资源目录与 CSS 样式

在项目根目录下创建 static 文件夹,并在其中新建 style.css:

static/style.css
body {
  font-family: -apple-system, sans-serif;
  background-color: #f7fafc;
  color: #2d3748;
  padding: 40px;
}
.container {
  max-width: 600px;
  margin: 0 auto;
  background: #ffffff;
  padding: 30px;
  border-radius: 8px;
  box-shadow: 0 4px 6px rgba(0,0,0,0.05);
}
h1 {
  color: #6487a5;
}
li {
  padding: 6px 0;
  border-bottom: 1px dashed #e2e8f0;
}

3. 修改 app.py 实现模板渲染

引入 render_template 函数,将参数传递给模板:

app.py 更新完整代码
from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def home():
    user_name = "Python 开发者"
    task_list = ["搭建虚拟环境", "安装 Flask 核心库", "配置路由规则", "编写 Jinja2 模板"]
    # 将变量作为关键字参数传递给 render_template
    return render_template(
        "index.html",
        title="Flask 动态首页",
        user=user_name,
        tasks=task_list
    )

if __name__ == "__main__":
    app.run(debug=True)

刷新浏览器页面,你将看到一个具有精致卡片样式、动态姓名问候以及通过 for 循环渲染出来的列表清单,这标志着你已经成功打通了 Flask 的完整 MVC 渲染链条!

七、初学者常见问题与避坑指南

  • 端口被占用(Address already in use / 5000 端口冲突):
    在 macOS Monterey 及以上版本中,系统内置的“隔空播放接收器”(AirPlay Receiver)默认占用了 5000 端口。此时可以显式指定其他端口启动:
    flask --app app run --port 5001
    或者在 Python 脚本中修改为 app.run(port=5001, debug=True)。
  • 报错 jinja2.exceptions.TemplateNotFound: index.html:
    Flask 严格寻找名为 templates(全小写、复数带有字母 s)的文件夹。请务必检查文件夹名是否误拼写为 template 或直接放置在根目录。
  • 修改 HTML/CSS 页面后浏览器没有即时变化:
    浏览器通常会对 CSS 等静态文件进行强缓存。调试时可尝试强制刷新(Ctrl + F5 或 Cmd + Shift + R),或者在浏览器的开发者工具中勾选“Disable cache(停用缓存)”。
  • 开发服务器不要直接用于公网生产环境:
    flask run 启动的是内置的 WSGI 开发服务器,专为调试设计,单进程单线程且缺乏完善的安全加固。在部署到正式公网时,应搭配 Gunicorn 或 uWSGI 作为应用服务器,并前置 Nginx 处理静态文件与反向代理。

八、教程要点回顾与学习进阶路径

通过本文的操作,你已经掌握了 Python Flask 最基础也是最关键的核心知识树。为了帮助你在脑海中建立完整的概念模型并明确后续进阶方向,我们通过以下总结图进行全面梳理。

用Python Flask搭建第一个网页应用详细教程
图 4:Flask 核心知识架构与后续工程能力演进图谱

完成本篇教程后,你已掌握了现代轻量级 Web 开发的核心主干。建议下一步尝试通过 HTML <form> 标签构建一个用户提交表单,并在 Flask 视图中使用 request.method == 'POST' 接收数据,逐步迈向更具实用价值的 Web 交互应用。

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。