命令行界面¶
安装 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
在
hello
中使用app2
Flask 实例。--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
选项监视其他文件。多个路径使用 :
分隔,或在 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
中设置的变量,后者又优先于 .flaskenv
中设置的变量。 .flaskenv
应用于公共变量,例如 FLASK_APP
,而 .env
不应提交到您的存储库,以便它可以设置私有变量。
目录从调用 flask
的目录向上扫描以找到文件。
这些文件仅由 flask
命令或调用 run()
加载。如果您想在生产环境中运行时加载这些文件,您应手动调用 load_dotenv()
。
设置命令选项¶
Click 被配置为从环境变量加载命令选项的默认值。变量使用模式 FLASK_COMMAND_OPTION
。例如,要设置运行命令的端口,而不是 flask run --port 8000
$ export FLASK_RUN_PORT=8000
$ flask run
* Running on http://127.0.0.1:8000/
$ set -x FLASK_RUN_PORT 8000
$ flask run
* Running on http://127.0.0.1:8000/
> set FLASK_RUN_PORT=8000
> flask run
* Running on http://127.0.0.1:8000/
> $env:FLASK_RUN_PORT = 8000
> flask run
* Running on http://127.0.0.1:8000/
这些内容可以像 FLASK_APP
一样添加到 .flaskenv
文件中,以控制默认命令选项。
禁用 dotenv¶
如果 flask
命令检测到 dotenv 文件但未安装 python-dotenv,它将显示一条消息。
$ flask run
* Tip: There are .env files present. Do "pip install python-dotenv" to use them.
通过设置 FLASK_SKIP_DOTENV
环境变量,即使安装了 python-dotenv,您也可以告诉 Flask 不要加载 dotenv 文件。如果您想手动加载它们,或者如果您正在使用已经加载它们的项目运行程序,这会很有用。请记住,必须在加载应用程序之前设置环境变量,否则它不会按预期配置。
$ export FLASK_SKIP_DOTENV=1
$ flask run
$ set -x FLASK_SKIP_DOTENV 1
$ flask run
> set FLASK_SKIP_DOTENV=1
> flask run
> $env:FLASK_SKIP_DOTENV = 1
> flask run
virtualenv 中的环境变量¶
如果您不想安装 dotenv 支持,您仍然可以通过将它们添加到 virtualenv 的 activate
脚本的末尾来设置环境变量。激活 virtualenv 将设置变量。
Unix Bash,.venv/bin/activate
$ export FLASK_APP=hello
Fish,.venv/bin/activate.fish
$ set -x FLASK_APP hello
Windows CMD,.venv\Scripts\activate.bat
> set FLASK_APP=hello
Windows Powershell,.venv\Scripts\activate.ps1
> $env: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 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
对象时指定 cli_group
参数,或稍后使用 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()
装饰器添加的命令将在推送应用程序上下文后执行,因此你的自定义命令和参数可以访问应用程序及其配置。可以使用 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 项目相同的虚拟环境中,你就可以运行 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 运行配置来运行开发服务器。对于社区版以及除 run
之外的其他命令,您需要创建一个自定义运行配置。这些说明对于您使用的任何其他 IDE 应该都是类似的。
在 PyCharm 中,在您的项目打开的情况下,从菜单栏中单击运行,然后转到编辑配置。您将看到类似于此的屏幕

为 flask run
创建配置后,您可以复制并更改它以调用任何其他命令。
单击+(添加新配置)按钮并选择Python。为配置指定一个名称,例如“flask run”。
单击脚本路径下拉列表并将其更改为模块名称,然后输入 flask
。
参数字段设置为要执行的 CLI 命令以及任何参数。此示例使用 --app hello run --debug
,它将在调试模式下运行开发服务器。 --app hello
应该是导入或包含 Flask 应用程序的文件。
如果您已将项目作为包安装在 virtualenv 中,则可以取消选中PYTHONPATH 选项。这将更准确地匹配您以后的部署方式。
单击确定以保存并关闭配置。在 PyCharm 主窗口中选择配置,然后单击其旁边的播放按钮以运行服务器。
现在您已为 flask run
创建了配置,您可以复制该配置并将参数参数更改为运行不同的 CLI 命令。