如何从项目外部优雅运行Hatch项目中的可执行脚本？

问题场景 #

• 项目根目录：/home/me/projects/myproject/，pyproject.toml中配置了可执行脚本：

  [project.scripts]
  myrunnable = "myproject.main:main"
  

• 当前处于/home/me/，需运行myrunnable，但该脚本要求在项目根目录执行；现有方式需切换目录或使用pushd/popd，希望找到官方优雅方案。

解决方案 #

方案1：子shell中切换目录执行 #

无需改变当前shell的工作目录，直接在子shell中完成目录切换和命令执行：

cd "/home/me/projects/myproject/" && hatch run myrunnable

方案2：使用HATCH_PROJECT_DIR环境变量 #

通过环境变量指定项目目录，同时强制脚本在项目根目录运行：

HATCH_PROJECT_DIR="/home/me/projects/myproject/" hatch run --cwd "$HATCH_PROJECT_DIR" myrunnable

该方式明确告知Hatch项目位置，同时确保脚本的工作目录为项目根目录，完美适配脚本的路径依赖需求。

方案3：使用Hatch的--project参数（Hatch 1.10.0+） #

若使用较新版本的Hatch，可直接用--project（或缩写-p）指定项目目录，搭配--cwd设置工作目录：

hatch --project "/home/me/projects/myproject/" run --cwd "/home/me/projects/myproject/" myrunnable

方案4：创建别名简化命令 #

若需频繁执行，可在shell配置文件（如~/.bashrc或~/.zshrc）中添加别名：

alias hatch-project-run='HATCH_PROJECT_DIR="$1" hatch run --cwd "$1" "${@:2}"'

保存后重载配置（如source ~/.bashrc），之后即可用简洁命令运行：

hatch-project-run "/home/me/projects/myproject/" myrunnable

说明 #

之前尝试的hatch --config "/home/me/projects/myproject/pyproject.toml" run myrunnable失败，原因是该命令仅指定了配置文件路径，但脚本的工作目录仍为当前目录/home/me/，不符合脚本对项目根目录的依赖要求。上述方案均解决了工作目录的问题，同时保持命令的简洁性。

内容的提问来源于stack exchange，提问作者Olivier Cailloux