命令行界面

在虚拟环境中安装 Flask 时会同时安装 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

使用 app2 中的Flask实例 hello .

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

调用 hello 中的 create_app 工厂，把 'dev' 作为参数。

如果 --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 option. Multiple paths are separated with :, or `` ；``在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 option. Multiple patterns are separated with :, or `` ；``在Windows上。

打开一个 Shell

要探索应用程序中的数据，可以使用 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() 添加其他自动导入。

通过 virturalenv 设置环境变量

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

您可以使用Flaskdotenv支持自动设置环境变量，而不是在每次运行命令时传递选项，或在每次打开新终端时传递环境变量。

如果 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 模式。例如，要为运行命令设置端口，不使用 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_SKIP_DOTENV 环境变量。如果您想手动加载它们，或者您使用的是已经加载它们的项目运行程序，那么这将非常有用。请记住，必须在加载应用程序之前设置环境变量，否则将无法按预期进行配置。

BashFishCMDPowershell

$ export FLASK_SKIP_DOTENV=1
$ flask run

通过 virturalenv 设置环境变量

如果不想安装 dotenv 支持，可以通过把它们添加到 virtualenv 的 activate 文件末尾来设置环境变量。激活 virtualenv 时会设置环境变量。

BashFishCMDPowershell

Unix Bash， .venv/bin/activate **

$ export FLASK_APP=hello

与此相比，最好使用dotenv支持，因为 .flaskenv 可以提交到存储库，当提取项目代码后就可以自动发挥作用。

自定义命令

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

此示例添加了命令 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 命令 。

用蓝图注册命令

如果应用程序使用蓝图，则可以选择直接在蓝图上注册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

可以通过指定 cli_group 创建时的参数 Blueprint 对象，或稍后使用 app.register_blueprint(bp, 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() Decorator将与推送的应用程序上下文一起执行，因此您的自定义命令和参数可以访问应用程序及其配置。这个 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 entry point 。这对于想要在安装时添加命令的扩展非常有用。入口点在 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脚本可能会更方便。与其使用 --app 让Flask加载您的应用程序，您可以创建自己的Click对象并将其导出为 console script 入口点。

创建一个 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提供了一个特殊的FlaskRun配置来运行开发服务器。对于Community Edition，以及其他命令 run ，您需要创建自定义运行配置。这些说明应该与您使用的任何其他IDE类似。

在PyCharm中，打开您的项目，单击 Run 从菜单栏中并转到 Edit Configurations 。您将看到类似以下内容的屏幕：

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

单击 + (Add New Configuration) 按钮并选择 Python 。给配置起一个名字，比如“flaskrun”。

单击 Script path 下拉列表，并将其更改为 Module name ，然后输入 flask 。

这个 Parameters 字段设置为CLI命令以与任何参数一起执行。此示例使用 --app hello run --debug ，它将以调试模式运行开发服务器。 --app hello 应该是您的Flaskapp的导入或文件。

如果您在您的Virtualenv中以包的形式安装了项目，则可以取消选中 PYTHONPATH 选择。这将更准确地匹配您稍后部署的方式。

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

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