Flask GitHub 快速入门指南 – wiki基地

作者： /

Flask GitHub 快速入门指南：构建你的第一个网络应用并进行版本控制

欢迎来到网络开发的精彩世界！如果你是 Python 爱好者，那么 Flask 绝对是构建轻量级网络应用的绝佳选择。Flask 是一个微框架，它不强制你使用特定的工具或库，提供了极大的灵活性。而 GitHub，作为全球最大的代码托管平台，是进行版本控制、协作和展示项目的首选工具。

将 Flask 应用与 GitHub 结合，不仅能帮你记录代码的每一次改动，还能让你轻松与他人协作，或者仅仅是安全地备份你的项目。本指南将带你一步步从零开始，创建一个简单的 Flask 应用，并通过 Git 将其推送到 GitHub。我们将详细解释每个步骤，确保即使是初学者也能轻松掌握。

预计阅读时间：约 20-30 分钟

前言：准备就绪

在开始之前，你需要确保你的系统已经安装了必要的工具。别担心，这些都是网络开发和版本控制的基础，安装过程通常很简单。

  1. Python: Flask 是一个 Python 框架，所以你需要安装 Python。建议安装 Python 3.6 或更高版本。你可以从 Python 官网 下载安装包。
  2. pip: pip 是 Python 的包管理器，用于安装 Flask 和其他库。它通常随 Python 一起安装。
  3. Git: Git 是一个分布式版本控制系统，用于跟踪代码改动。你可以从 Git 官网 下载安装包。安装后，建议进行一些基本的配置，比如设置你的用户名和邮箱，这些信息会与你的提交记录关联：
    bash
    git config --global user.name "Your Name"
    git config --global user.email "[email protected]"
  4. GitHub 账户: 如果你还没有 GitHub 账户，请前往 GitHub 官网 注册一个免费账户。
  5. 代码编辑器: 一个好的代码编辑器（如 VS Code, PyCharm, Sublime Text, Atom 等）会让你的编码体验更愉快。

确保所有工具都已安装并可通过命令行访问。你可以在终端中输入以下命令来检查：

bash
python --version
pip --version
git --version

如果这些命令都能正确输出版本信息，说明你已经准备好了！

第一部分：创建你的第一个 Flask 应用

我们将创建一个非常简单的 Flask 应用，它只显示一个“Hello, Flask!”消息。

步骤 1: 创建项目目录

首先，在你的电脑上选择一个合适的位置，创建一个新的文件夹来存放你的项目。例如，在桌面或文档目录下创建一个名为 my_flask_app 的文件夹。

bash
mkdir my_flask_app
cd my_flask_app

mkdir 创建文件夹，cd 进入该文件夹。

步骤 2: 创建虚拟环境

强烈建议在每个 Python 项目中使用虚拟环境（Virtual Environment）。虚拟环境可以在项目之间隔离依赖库，避免版本冲突问题。

在项目目录 (my_flask_app) 中，使用以下命令创建虚拟环境。Python 3.3+ 内置了 venv 模块，无需额外安装。

bash
python -m venv venv

这会在当前目录下创建一个名为 venv 的文件夹（你也可以取其他名字，但 venv 是约定俗成的）。这个文件夹包含了 Python 解释器的副本以及 pip。

步骤 3: 激活虚拟环境

在安装 Flask 之前，你需要激活这个虚拟环境。激活后，你安装的所有 Python 包都会被安装到这个虚拟环境中，而不是全局的 Python 环境。

  • Windows:
    bash
    venv\Scripts\activate
    或者使用 PowerShell:
    powershell
    .\venv\Scripts\Activate.ps1
  • macOS/Linux:
    bash
    source venv/bin/activate

激活成功后，你的终端提示符前会显示虚拟环境的名称，通常是 (venv)，例如：

bash
(venv) your_username@your_computer:~/my_flask_app$

这表明你现在正在虚拟环境中工作。

步骤 4: 安装 Flask

虚拟环境激活后，使用 pip 安装 Flask：

bash
pip install Flask

pip 会自动下载 Flask 及其所有依赖项并安装到当前的虚拟环境中。

步骤 5: 编写你的第一个 Flask 应用代码

在 my_flask_app 目录中，创建一个新的 Python 文件，命名为 app.py（这是 Flask 应用的常见入口文件名）。用你的代码编辑器打开 app.py，然后输入以下代码：

“`python

app.py

from flask import Flask

创建一个 Flask 应用实例

name 是一个特殊的 Python 变量，当文件作为主程序运行时，它的值是 ‘main‘

Flask 需要知道在哪里查找资源（如模板和静态文件），这个参数帮助 Flask 确定根目录

app = Flask(name)

使用路由装饰器定义一个 URL 路径 ‘/’

当用户访问网站的根目录时 (如 http://127.0.0.1:5000/)，会触发这个函数

@app.route(‘/’)
def hello_world():
“””
定义一个视图函数，当访问 ‘/’ 路由时被调用。
它返回一个简单的字符串作为响应。
“””
return ‘Hello, Flask!’

这是一个 Python 的惯例，确保当这个文件直接被执行时，运行 Flask 开发服务器

if name == ‘main‘:
# app.run() 启动 Flask 内置的开发服务器
# debug=True 参数开启调试模式，方便开发过程中查看错误信息和自动重载代码
app.run(debug=True)
“`

保存 app.py 文件。

代码解释：

  • from flask import Flask: 导入 Flask 类。
  • app = Flask(__name__): 创建 Flask 应用的实例。__name__ 告诉 Flask 当前模块的名称，用于查找资源。
  • @app.route('/'): 这是一个装饰器，它告诉 Flask，当用户访问网站的根 URL (/) 时，应该调用紧随其后的函数。
  • def hello_world():: 定义一个 Python 函数，这个函数被称为“视图函数”。当对应的 URL 被访问时，Flask 会执行这个函数。
  • return 'Hello, Flask!': 视图函数返回的内容会被发送到用户的浏览器。在这里，它返回一个简单的字符串。
  • if __name__ == '__main__':: 这块代码只有在直接运行 python app.py 文件时才会执行。
  • app.run(debug=True): 启动 Flask 内置的开发服务器。debug=True 开启调试模式，这样你修改代码后不需要手动重启服务器，并且在出现错误时会显示详细的错误信息。

步骤 6: 运行 Flask 应用

在虚拟环境激活的状态下，回到终端，确保你在 my_flask_app 目录下，然后运行你的应用：

bash
python app.py

如果一切正常，你将看到类似以下的输出：

* Serving Flask app 'app'
* Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with stat
* Debugger is active!
* Debugger PIN: XXX-XXX-XXX

这表示你的 Flask 应用已经在本地的开发服务器上运行起来了。默认情况下，它运行在 http://127.0.0.1:5000/（也就是 http://localhost:5000/）。

打开你的网络浏览器，访问 http://127.0.0.1:5000/。你应该能看到页面上显示 Hello, Flask!。

恭喜你！你已经成功创建并运行了你的第一个 Flask 应用。

要停止服务器，回到终端并按下 Ctrl + C。

步骤 7 (可选): 添加另一个页面

为了让应用稍微丰富一点，我们再添加一个页面。修改 app.py 如下：

“`python

app.py

from flask import Flask

app = Flask(name)

@app.route(‘/’)
def hello_world():
return ‘Hello, Flask!’

添加一个新的路由和视图函数

@app.route(‘/about’)
def about():
return ‘This is a simple Flask app.’

if name == ‘main‘:
app.run(debug=True)
“`

保存文件。由于你在 debug=True 模式下运行服务器，它应该会自动检测到文件改动并重启。如果没有自动重启，手动 Ctrl+C 停止服务器，然后再次运行 python app.py。

现在，访问 http://127.0.0.1:5000/about，你应该能看到 “This is a simple Flask app.”。

步骤 8 (可选): 使用 HTML 模板

直接在视图函数中返回 HTML 字符串对于简单应用来说可以，但对于更复杂的页面来说，更好的做法是使用 HTML 模板。Flask 使用 Jinja2 模板引擎。

  1. 创建 templates 文件夹: 在 my_flask_app 目录下，创建一个名为 templates 的新文件夹。Flask 默认会在这个文件夹中查找模板文件。

    bash
    mkdir templates

  2. 创建 HTML 模板文件: 在 templates 文件夹中，创建两个 HTML 文件：index.html 和 about.html。

    templates/index.html:
    html
    <!DOCTYPE html>
    <html>
    <head>
    <title>Home</title>
    </head>
    <body>
    <h1>Welcome to my Flask App!</h1>
    <p>Hello, Flask!</p>
    <p><a href="/about">About Page</a></p>
    </body>
    </html>

    templates/about.html:
    html
    <!DOCTYPEanesh html>
    <html>
    <head>
    <title>About</title>
    </head>
    <body>
    <h1>About This App</h1>
    <p>This is a simple Flask app built for a quick start guide.</p>
    <p><a href="/">Home Page</a></p>
    </body>
    </html>

  3. 修改 app.py 使用模板: 修改 app.py 文件，导入 render_template 函数，并用它来渲染 HTML 文件。

    “`python

    app.py

    from flask import Flask, render_template # 导入 render_template

    app = Flask(name)

    @app.route(‘/’)
    def index(): # 将函数名改为 index 更具描述性
    return render_template(‘index.html’) # 渲染 templates/index.html

    @app.route(‘/about’)
    def about():
    return render_template(‘about.html’) # 渲染 templates/about.html

    if name == ‘main‘:
    app.run(debug=True)
    “`

    保存文件，重新运行或等待自动重启。现在访问 http://127.0.0.1:5000/ 和 http://127.0.0.1:5000/about，你将看到更具结构的 HTML 页面。

至此，你的第一个 Flask 应用已经有了一个基本的结构，包含两个页面并使用了模板。

第二部分：使用 Git 进行版本控制

现在你的应用已经可以工作了，是时候开始使用 Git 来跟踪你的代码改动了。

1. 初始化 Git 仓库

在你的项目目录 my_flask_app 中，运行以下命令来初始化一个 Git 仓库：

bash
git init

这会在 my_flask_app 目录下创建一个隐藏的 .git 文件夹。这个文件夹包含了 Git 跟踪项目所需的所有信息。

终端会显示：

Initialized empty Git repository in /path/to/your/my_flask_app/.git/

2. 查看 Git 状态

随时可以使用 git status 命令来查看当前 Git 仓库的状态：

bash
git status

第一次运行 git status，你会看到 Git 告诉你目录中有一些“未跟踪的文件”（Untracked files）：app.py, templates/, venv/。

“`
On branch master

No commits yet

Untracked files:
(use “git add …” to include in what will be committed)
app.py
templates/
venv/

nothing added to commit but untracked files present (use “git add” to track)
“`

3. 创建 .gitignore 文件

注意到了吗？venv/ 目录也在未跟踪文件列表中。虚拟环境通常包含很多文件，而且这些文件是可以通过 pip install -r requirements.txt 重新生成的，不应该被 Git 跟踪。

为了告诉 Git 忽略 venv/ 目录和其他不需要跟踪的文件（比如编译生成的文件，IDE 配置文件等），我们需要创建一个 .gitignore 文件。

在 my_flask_app 目录中，创建一个名为 .gitignore 的文件（注意文件名前面的点）。使用你的代码编辑器打开它，添加以下内容：

“`gitignore

.gitignore

忽略 Python 虚拟环境目录

venv/

忽略 Python 编译生成的文件 (.pyc)

pycache/
*.pyc

忽略编辑器和IDE的临时文件或配置 (示例，根据你使用的编辑器添加)

.vscode/ # VS Code 配置文件
.idea/ # PyCharm 配置文件
.swp # Vim 交换文件
~ # Emacs/Vim 临时文件

忽略操作系统生成的文件

.DS_Store # macOS
Thumbs.db # Windows

忽略 requirements.txt 文件，因为我们稍后会生成它并添加到仓库 (但通常 requirements.txt 是需要添加到仓库的)

为了演示目的，我们暂时不忽略 requirements.txt

如果你不想将 requirements.txt 放入仓库，可以取消下一行的注释：

requirements.txt

“`

保存 .gitignore 文件。现在再次运行 git status：

bash
git status

你会发现 venv/ 目录不再出现在未跟踪文件列表中了。.gitignore 文件本身现在是未跟踪的。

“`
On branch master

No commits yet

Untracked files:
(use “git add …” to include in what will be committed)
.gitignore
app.py
templates/

nothing added to commit but untracked files present (use “git add” to track)
“`

4. 将文件添加到暂存区

现在，我们需要告诉 Git 哪些文件是我们想要提交的。我们将所有当前未被忽略的文件（.gitignore, app.py, templates/ 目录及其内容）添加到暂存区（Staging Area）。

“`bash
git add .gitignore app.py templates/

或者更简洁地添加所有未被忽略的文件：

git add .

“`

git add . 命令会将当前目录下所有未被忽略的、有改动的文件添加到暂存区。

再次运行 git status：

bash
git status

这次，你会看到文件列表从“未跟踪的文件”变成了“要被提交的更改”（Changes to be committed），它们变成了绿色。

“`
On branch master

No commits yet

Changes to be committed:
(use “git rm –cached …” to unstage)
new file: .gitignore
new file: app.py
new file: templates/about.html
new file: templates/index.html
“`

5. 提交更改

文件进入暂存区后，就可以进行提交（Commit）了。提交是版本控制的基本单位，它记录了项目在某个特定时间点的快照以及相关的描述信息。

bash
git commit -m "Initial commit: Setup basic Flask app with templates"

git commit 命令用于创建提交。-m 标志后面跟着一个简短的提交消息（Commit Message），用于描述这次提交做了什么。编写有意义的提交消息是一个好习惯。

提交成功后，Git 会输出本次提交的信息，包括分支、提交 ID（一个哈希值）、提交者、日期和提交消息。

[master (root-commit) a1b2c3d] Initial commit: Setup basic Flask app with templates
4 files changed, 40 insertions(+)
create mode 100644 .gitignore
create mode 100644 app.py
create mode 100644 templates/about.html
create mode 100644 templates/index.html

现在你的项目目录的当前状态已经被 Git 记录下来了。你可以随时查看提交历史 (git log)。

6. 忽略依赖列表文件 (requirements.txt)

在项目开发中，记录项目依赖是非常重要的，这样其他人（或未来的你）可以轻松安装运行项目所需的所有库。pip 可以帮我们生成这个列表。

确保你的虚拟环境处于激活状态，然后在项目根目录运行：

bash
pip freeze > requirements.txt

pip freeze 命令会列出当前虚拟环境中安装的所有包及其版本。> 符号将输出重定向到一个名为 requirements.txt 的文件中。

打开 requirements.txt 文件，你会看到类似这样的内容：

Flask==2.3.3
Jinja2==3.1.2
Werkzeug==2.3.7
itsdangerous==2.1.2
MarkupSafe==2.1.3

（具体的版本号可能会不同）

现在，.gitignore 文件中我们并没有忽略 requirements.txt，所以我们可以将其添加到 Git 中。

bash
git add requirements.txt
git commit -m "Add requirements.txt"

现在你的本地 Git 仓库已经包含了项目的代码、忽略文件和依赖列表。

第三部分：连接本地仓库与 GitHub

现在，我们将把你本地的 Git 仓库连接到 GitHub，并将代码推送到 GitHub 上进行托管。

1. 在 GitHub 上创建新的仓库

  1. 登录你的 GitHub 账户。
  2. 点击页面右上角的 “+” 图标，选择 “New repository”（新建仓库）。
  3. 在 “Repository name” 字段中输入你想要的项目名称，例如 my_flask_app。
  4. 你可以添加描述（可选）。
  5. 选择仓库的可见性（Public 公开 或 Private 私有）。对于大多数开源项目或个人项目，Public 都可以。
  6. 重要: 不要勾选 “Add a README file”、”Add .gitignore” 或 “Choose a license”。这些文件我们已经在本地创建或不需要。
  7. 点击 “Create repository” 按钮。

创建成功后，GitHub 会显示一个页面，其中包含了将现有本地仓库推送到这个新创建的远程仓库的说明。寻找标题为 “…or push an existing repository from the command line” 的部分。它会提供两行命令，类似这样：

bash
git remote add origin https://github.com/你的GitHub用户名/my_flask_app.git
git branch -M main # 或 master, 取决于你的Git配置和GitHub默认设置
git push -u origin main # 或 master

2. 将本地仓库关联到 GitHub 远程仓库

回到你的本地终端，确保你在项目目录 my_flask_app 中。复制并执行 GitHub 页面上提供的第一行命令：

bash
git remote add origin https://github.com/你的GitHub用户名/my_flask_app.git

这条命令的作用是：
* git remote add: 添加一个新的远程仓库。
* origin: 这是给这个远程仓库起的一个别名，origin 是 Git 中约定俗成的别名，代表你的主远程仓库。
* https://github.com/你的GitHub用户名/my_flask_app.git: 这是你的 GitHub 仓库的 URL。请将 你的GitHub用户名 替换为你自己的 GitHub 用户名。

你可以运行 git remote -v 来查看你已经配置的远程仓库列表：

bash
git remote -v

输出应该类似：

origin https://github.com/你的GitHub用户名/my_flask_app.git (fetch)
origin https://github.com/你的GitHub用户名/my_flask_app.git (push)

3. 推送本地提交到 GitHub

现在，你可以将本地的提交推送到 GitHub 仓库了。使用 GitHub 页面上提供的第三行命令（第二行 git branch -M main 用于将你的本地分支重命名为 main，如果你的本地分支已经是 main 或 master 且与 GitHub 默认设置一致，这步可能不是必须的，但执行一次也无妨）：

bash
git branch -M main # 如果你的本地主分支不是 main 或 master，执行这步进行重命名
git push -u origin main # 将本地的 main 分支推送到 origin 远程仓库

  • git push: 执行推送操作。
  • -u origin main: -u (或 --set-upstream) 设置本地 main 分支跟踪远程的 origin/main 分支。这样以后你只需要简单地输入 git push 或 git pull 即可，无需指定 origin main。origin 是远程仓库别名，main 是要推送的分支名称。GitHub 的默认主分支现在通常是 main，而传统的 Git 默认分支是 master。请根据你的实际情况和 GitHub 页面上的提示选择 main 或 master。

执行 git push 命令后，Git 可能会要求你输入 GitHub 的用户名和密码。如果你开启了双重认证，可能需要使用 Personal Access Token (PAT) 而不是普通密码。有关如何生成和使用 PAT，请参考 GitHub 的文档。

推送成功后，终端会显示一些信息，表明本地的提交已经被发送到远程仓库。

现在，刷新你在 GitHub 上创建的仓库页面，你会看到你的代码文件 (app.py, .gitignore, requirements.txt, templates/ 目录) 已经出现在仓库中了！

第四部分：后续开发与版本控制流程

你的项目现在已经在本地和 GitHub 上都存在了。接下来的开发流程通常是：

  1. 在本地进行代码修改: 在你的代码编辑器中修改 app.py，添加新的功能，修改模板文件等。
  2. 查看改动: 随时使用 git status 查看你修改了哪些文件。
  3. 添加到暂存区: 使用 git add <filename> 或 git add . 将你想要包含在下一次提交中的文件添加到暂存区。
  4. 提交更改: 使用 git commit -m "描述本次提交的改动" 创建一个新的提交。写一个清晰、简洁的提交消息非常重要。
  5. 推送到 GitHub: 使用 git push 将你的本地新提交发送到 GitHub 远程仓库。

示例：修改 homepage 标题并推送到 GitHub

  1. 修改 templates/index.html，将 <h1>Welcome to my Flask App!</h1> 改为 <h1>My Awesome Flask App</h1>。保存文件。
  2. 在终端中（确保虚拟环境激活）：
    bash
    (venv) cd my_flask_app
    (venv) git status
    你会看到 templates/index.html 被列在 “Changes not staged for commit” 下面。
  3. 将改动添加到暂存区：
    bash
    (venv) git add templates/index.html
    (venv) git status
    现在 templates/index.html 在 “Changes to be committed” 下面。
  4. 提交更改：
    bash
    (venv) git commit -m "Update homepage title in template"
    一个新的提交被创建。
  5. 推送到 GitHub：
    bash
    (venv) git push
    Git 会将你的本地 main 分支上的新提交推送到 origin 远程仓库。刷新 GitHub 页面，你将看到新的提交记录和文件内容的改变。

总结与展望

恭喜你！你已经成功地：

  • 创建了一个简单的 Flask 网络应用。
  • 学会了使用虚拟环境管理项目依赖。
  • 了解了 Flask 的基本结构和运行方式。
  • 使用 Git 对项目进行了初始化和首次提交。
  • 创建了 .gitignore 文件来忽略不需要跟踪的文件。
  • 生成了 requirements.txt 文件记录项目依赖。
  • 在 GitHub 上创建了远程仓库。
  • 将本地仓库与 GitHub 远程仓库关联。
  • 成功地将本地代码推送到 GitHub。
  • 掌握了基本的 Git 工作流程（修改 -> 添加 -> 提交 -> 推送）。

这仅仅是 Flask 和 Git/GitHub 世界的冰山一角。接下来，你可以继续探索：

Flask 进阶:

  • 更复杂的路由和 URL 构建 (url_for)
  • 处理表单数据 (使用 WTForms 库)
  • 数据库集成 (使用 Flask-SQLAlchemy 库)
  • 用户认证和授权
  • 使用蓝图（Blueprints）组织大型应用
  • 部署你的 Flask 应用到生产环境 (如 Heroku, PythonAnywhere, AWS, Vercel 等)

Git/GitHub 进阶:

  • 分支（Branches）和合并（Merging）：学习如何在不同的分支上开发新功能，并在完成后合并回主分支。
  • 拉取请求（Pull Requests）：在团队协作中如何提出代码修改建议并进行代码审查。
  • 克隆仓库 (git clone)：如何从 GitHub 上获取一个现有项目到本地。
  • 拉取更改 (git pull)：如何在团队协作中获取其他人推送到远程仓库的最新代码。
  • 解决合并冲突（Merge Conflicts）。
  • Git Log 的更多用法。
  • GitHub 的其他功能，如 Issues (问题跟踪), Projects (项目管理), Actions (自动化工作流) 等。

通过持续学习和实践，你将能够构建更强大、更复杂的网络应用，并高效地管理你的代码。

希望这篇详细的指南能帮助你顺利迈出 Flask 和 GitHub 集成的第一步！如果在过程中遇到任何问题，不要灰心，查阅官方文档、搜索在线资源或在开发者社区提问都是非常有效的解决方法。

祝你编程愉快！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部