命令行界面

安装 Flask 会在您的 virtualenv 中安装 flask 脚本，这是一个 Click 命令行界面。从终端执行此脚本可以访问内置命令、扩展命令和应用程序定义的命令。--help 选项将提供有关任何命令和选项的更多信息。

应用程序发现

flask 命令由 Flask 安装，而不是您的应用程序；必须告知它在哪里找到您的应用程序才能使用它。--app 选项用于指定如何加载应用程序。

虽然 --app 支持多种指定应用程序的选项，但大多数用例应该很简单。以下是典型值

(无)

导入名称 “app” 或 “wsgi”（作为 “.py” 文件或包），自动检测应用程序（app 或 application）或工厂（create_app 或 make_app）。

--app hello

导入给定的名称，自动检测应用程序（app 或 application）或工厂（create_app 或 make_app）。

---

--app 有三个部分：一个可选的路径，用于设置当前工作目录；一个 Python 文件或点式导入路径；以及一个可选的实例或工厂的变量名。如果名称是工厂，则可以选择在其后跟括号中的参数。以下值演示了这些部分

--app src/hello

将当前工作目录设置为 src，然后导入 hello。

--app hello.web

导入路径 hello.web。

--app hello:app2

使用 hello 中的 app2 Flask 实例。

--app 'hello:create_app("dev")'

使用字符串 'dev' 作为参数调用 hello 中的 create_app 工厂。

如果未设置 --app，则命令将尝试导入 “app” 或 “wsgi”（作为 “.py” 文件或包），并尝试检测应用程序实例或工厂。

在给定的导入中，命令查找名为 app 或 application 的应用程序实例，然后查找任何应用程序实例。如果未找到实例，则命令查找名为 create_app 或 make_app 的工厂函数，该函数返回一个实例。

如果工厂名称后跟括号，则括号中的内容将被解析为 Python 字面量，并作为参数和关键字参数传递给该函数。这意味着字符串仍然必须用引号引起来。

运行开发服务器

run 命令将启动开发服务器。在大多数情况下，它取代了 Flask.run() 方法。

$ flask --app hello run
 * Serving Flask app "hello"
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

警告

请勿使用此命令在生产环境中运行您的应用程序。仅在开发期间使用开发服务器。提供开发服务器是为了方便起见，但它并非设计为特别安全、稳定或高效。请参阅部署到生产环境，了解如何在生产环境中运行。

如果另一个程序已在使用端口 5000，您将在服务器尝试启动时看到 OSError: [Errno 98] 或 OSError: [WinError 10013]。请参阅 地址已被占用，了解如何处理这种情况。

调试模式

在调试模式下，默认情况下，flask run 命令将启用交互式调试器和重载器，并使错误更易于查看和调试。要启用调试模式，请使用 --debug 选项。

$ flask --app hello run --debug
 * Serving Flask app "hello"
 * Debug mode: on
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with inotify reloader
 * Debugger is active!
 * Debugger PIN: 223-456-919

--debug 选项也可以传递给顶层 flask 命令，以便为任何命令启用调试模式。以下两个 run 调用是等效的。

$ flask --app hello --debug run
$ flask --app hello run --debug

使用重载器监视和忽略文件

当使用调试模式时，每当您的 Python 代码或导入的模块发生更改时，重载器都会触发。重载器可以使用 --extra-files 选项监视其他文件。多个路径用 : 分隔，或在 Windows 上用 ; 分隔。

$ flask run --extra-files file1:dirA/file2:dirB/
 * Running on http://127.0.0.1:8000/
 * Detected change in '/path/to/file1', reloading

重载器还可以使用 fnmatch 模式和 --exclude-patterns 选项忽略文件。多个模式用 : 分隔，或在 Windows 上用 ; 分隔。

打开 Shell

要浏览应用程序中的数据，您可以使用 shell 命令启动交互式 Python shell。应用程序上下文将处于活动状态，并且将导入应用程序实例。

$ flask shell
Python 3.10.0 (default, Oct 27 2021, 06:59:51) [GCC 11.1.0] on linux
App: example [production]
Instance: /home/david/Projects/pallets/flask/instance
>>>

使用 shell_context_processor() 添加其他自动导入。

来自 dotenv 的环境变量

flask 命令支持使用环境变量为任何命令设置任何选项。变量的命名类似于 FLASK_OPTION 或 FLASK_COMMAND_OPTION，例如 FLASK_APP 或 FLASK_RUN_PORT。

您可以不必每次运行命令时都传递选项，也不必每次打开新终端时都传递环境变量，而是可以使用 Flask 的 dotenv 支持来自动设置环境变量。

如果安装了 python-dotenv，则运行 flask 命令将设置在文件 .env 和 .flaskenv 中定义的环境变量。您还可以使用 --env-file 选项指定要加载的额外文件。Dotenv 文件可用于避免必须手动设置 --app 或 FLASK_APP，以及使用类似于某些部署服务的工作方式的环境变量来设置配置。

命令行上设置的变量优先于在 .env 中设置的变量，而 .env 中设置的变量优先于在 .flaskenv 中设置的变量。.flaskenv 应该用于公共变量，例如 FLASK_APP，而 .env 不应提交到您的存储库，以便它可以设置私有变量。

目录从您调用 flask 的目录向上扫描以查找文件。

这些文件仅由 flask 命令或调用 run() 加载。如果您希望在生产环境中运行时加载这些文件，则应手动调用 load_dotenv()。

设置命令选项

Click 配置为从环境变量加载命令选项的默认值。变量使用模式 FLASK_COMMAND_OPTION。例如，要为 run 命令设置端口，而不是 flask run --port 8000

BashFishCMDPowershell

$ export FLASK_RUN_PORT=8000
$ flask run
 * Running on http://127.0.0.1:8000/

这些可以添加到 .flaskenv 文件中，就像 FLASK_APP 一样，以控制默认命令选项。

禁用 dotenv

如果 flask 命令检测到 dotenv 文件但未安装 python-dotenv，则会显示一条消息。

$ flask run
 * Tip: There are .env files present. Do "pip install python-dotenv" to use them.

您可以告诉 Flask 即使在安装了 python-dotenv 的情况下也不要加载 dotenv 文件，方法是设置 FLASK_SKIP_DOTENV 环境变量。如果您想手动加载它们，或者如果您正在使用已经加载它们的项目运行器，这将很有用。请记住，环境变量必须在应用程序加载之前设置，否则它将无法按预期配置。

BashFishCMDPowershell

$ export FLASK_SKIP_DOTENV=1
$ flask run

来自 virtualenv 的环境变量

如果您不想安装 dotenv 支持，您仍然可以通过将环境变量添加到 virtualenv 的 activate 脚本的末尾来设置环境变量。激活 virtualenv 将设置变量。

BashFishCMDPowershell

Unix Bash, .venv/bin/activate

$ export FLASK_APP=hello

建议使用 dotenv 支持而不是此方法，因为 .flaskenv 可以提交到存储库，以便它在项目签出的任何地方自动工作。

自定义命令

flask 命令是使用 Click 实现的。有关编写命令的完整信息，请参阅该项目的文档。

此示例添加了命令 create-user，该命令接受参数 name。

import click
from flask import Flask

app = Flask(__name__)

@app.cli.command("create-user")
@click.argument("name")
def create_user(name):
    ...

$ flask create-user admin

此示例添加了相同的命令，但作为 user create，组中的命令。如果您想组织多个相关命令，这将非常有用。

import click
from flask import Flask
from flask.cli import AppGroup

app = Flask(__name__)
user_cli = AppGroup('user')

@user_cli.command('create')
@click.argument('name')
def create_user(name):
    ...

app.cli.add_command(user_cli)

$ flask user create demo

请参阅 使用 CLI Runner 运行命令，以概述如何测试您的自定义命令。

使用蓝图注册命令

如果您的应用程序使用蓝图，您可以选择直接在蓝图上注册 CLI 命令。当您的蓝图注册到您的应用程序时，关联的命令将可用于 flask 命令。默认情况下，这些命令将嵌套在与蓝图名称匹配的组中。

from flask import Blueprint

bp = Blueprint('students', __name__)

@bp.cli.command('create')
@click.argument('name')
def create(name):
    ...

app.register_blueprint(bp)

$ flask students create alice

您可以在创建 Blueprint 对象时，或稍后使用 app.register_blueprint(bp, cli_group='...') 指定 cli_group 参数来更改组名称。以下是等效的

bp = Blueprint('students', __name__, cli_group='other')
# or
app.register_blueprint(bp, cli_group='other')

$ flask other create alice

指定 cli_group=None 将删除嵌套并将命令直接合并到应用程序级别

bp = Blueprint('students', __name__, cli_group=None)
# or
app.register_blueprint(bp, cli_group=None)

$ flask create alice

应用程序上下文

使用 Flask 应用程序的 cli 或 FlaskGroup command() 装饰器添加的命令将在推送应用程序上下文的情况下执行，因此您的自定义命令和参数可以访问应用程序及其配置。with_appcontext() 装饰器可用于获得相同的行为，但在大多数情况下不需要。

import click
from flask.cli import with_appcontext

@click.command()
@with_appcontext
def do_work():
    ...

app.cli.add_command(do_work)

插件

Flask 将自动加载在 flask.commands 入口点中指定的命令。这对于希望在安装时添加命令的扩展非常有用。入口点在 pyproject.toml 中指定

[project.entry-points."flask.commands"]
my-command = "my_extension.commands:cli"

在 my_extension/commands.py 内部，您可以导出 Click 对象

import click

@click.command()
def cli():
    ...

一旦该软件包与您的 Flask 项目安装在同一个 virtualenv 中，您就可以运行 flask my-command 来调用该命令。

自定义脚本

当您使用应用程序工厂模式时，定义您自己的 Click 脚本可能会更方便。您可以创建自己的 Click 对象并将其导出为 控制台脚本 入口点，而不是使用 --app 并让 Flask 加载您的应用程序。

创建 FlaskGroup 的实例，并将工厂传递给它

import click
from flask import Flask
from flask.cli import FlaskGroup

def create_app():
    app = Flask('wiki')
    # other setup
    return app

@click.group(cls=FlaskGroup, create_app=create_app)
def cli():
    """Management script for the Wiki application."""

在 pyproject.toml 中定义入口点

[project.scripts]
wiki = "wiki:cli"

以可编辑模式在 virtualenv 中安装应用程序，自定义脚本即可用。请注意，您不需要设置 --app。

$ pip install -e .
$ wiki run

自定义脚本中的错误

当使用自定义脚本时，如果在模块级代码中引入错误，重载器将失败，因为它无法再加载入口点。

flask 命令与您的代码是分开的，因此没有此问题，并且在大多数情况下推荐使用。

PyCharm 集成

PyCharm Professional 提供了特殊的 Flask 运行配置来运行开发服务器。对于 Community Edition，以及 run 以外的其他命令，您需要创建自定义运行配置。这些说明应与您使用的任何其他 IDE 类似。

在 PyCharm 中，打开您的项目后，从菜单栏中单击运行，然后转到编辑配置。您将看到类似于此屏幕的界面

一旦您为 flask run 创建了配置，您就可以复制并更改它以调用任何其他命令。

单击 + (添加新配置) 按钮，然后选择 Python。为配置命名，例如 “flask run”。

单击脚本路径下拉列表，并将其更改为模块名称，然后输入 flask。

参数字段设置为要执行的 CLI 命令以及任何参数。此示例使用 --app hello run --debug，它将在调试模式下运行开发服务器。--app hello 应该是包含您的 Flask 应用程序的导入或文件。

如果您已将项目作为软件包安装在 virtualenv 中，则可以取消选中 PYTHONPATH 选项。这将更准确地匹配您稍后部署的方式。

单击确定以保存并关闭配置。在主 PyCharm 窗口中选择配置，然后单击其旁边的播放按钮以运行服务器。

现在您已经有了 flask run 的配置，您可以复制该配置并更改参数参数以运行不同的 CLI 命令。