安装依赖：pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

1. 启动时命令

• jx app run --env=dev

2. 启动参数说明

• 其中 --env= 值对应 根目录下的环境变量配置文件: .env.dev，新增环境变量，只需新增环境变量文件 .env.xx 即可。

vscode 下调试面板设置

• 创建的 4 个文件

• 文件 大小 用途

• .vscode/settings.json 33 行 Python 解释器、文件排除、Pylance 设置

• .vscode/launch.json 108 行 Debug 配置（F5 / 调试面板）

• .vscode/tasks.json 140 行 任务（Terminal → Run Task，无需调试）

使用方式

• 方式 1：Debug 调试（打断点） 打开 VSCode → 左侧 Run and Debug 图标（▶️ 带虫子的） 顶部下拉框选择要启动的配置： jx app run --env=dev ← 走完整 jx CLI 流程 jx app run --env=prod jx app run --env=test app.py direct (--env=dev) ← 跳过 jx CLI，直接跑 app.py（推荐新手） Current Python File ← 跑当前打开的文件 在 server.py:84 lifespan 等关键位置打红点断点 按 F5 开始 debug

• 方式 2：Run 不调试（Terminal → Run Task） 顶部菜单 Terminal → Run Task... 选择任务： jx app run --env=dev ← 启动开发服务器 jx app doctor --env=dev ← 健康检查 jx app routes --env=dev ← 查看路由 jx db upgrade --env=dev ← 数据库迁移 关键设计点

1. 两种 Debug 入口可选 配置 入口 行为 优缺点 jx app run --env=dev python -m cli.main 走完 jx CLI 全流程，再 os.execvp 到 app.py 忠实还原命令行，但 os.execvp 可能让 debugpy 短暂失联 app.py direct (--env=dev) 直接 python app.py 跳过 jx CLI，直接调 uvicorn.run() 断点最稳定，推荐调试时用
2. 环境隔离 每个配置都有独立 --env=xxx，对应不同的 .env.dev / .env.prod / .env.test cwd: ${workspaceFolder} 确保从项目根目录启动（ProjectRuntimeLocator 会校验） env.PYTHONPATH: ${workspaceFolder} 确保模块导入能找到 cli/、config/、server.py 等
3. 推荐扩展（VSCode 启动时会自动提示安装）

✓ Python (ms-python.python) ← 必装 ✓ Python Debugger (ms-python.debugpy) ← 必装，F5 调试依赖 ✓ Pylance (ms-python.vscode-pylance) ← 智能补全 ✓ Black Formatter / Ruff ← 智能补全 ✓ Black Formatter / Ruff ← 代码格式化

python文件加载过程要点

• 从文件第一行开始，自上而下逐行执行（不只是 import 语句，赋值、函数调用、类定义等都执行）

• 遇到 import x.y 就递归进入 x.y 模块，把那整个文件执行一遍

• 同一个模块在同一个进程里只执行一次（执行完缓存到 sys.modules）

• 每个 .py 文件加载时，Python 创建一个模块对象，里面的所有"全局变量"实际是这个对象的属性

• Python 文件就是一段普通的可执行代码，只不过它有个模块对象作为命名空间容器。"导入" 只是触发另一个文件的执行，所有顶层语句（包括赋值、类实例化等"看起来像定义"的操作）都会在加载时立即执行。- Python 文件就是一段普通的可执行代码，只不过它有个模块对象作为命名空间容器。"导入" 只是触发另一个文件的执行，所有顶层语句（包括赋值、类实例化等"看起来像定义"的操作）都会在加载时立即执行。