开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载Workspace 环境是 Hatch 面向 monorepo 与多包协同开发的核心能力它允许你在同一个虚拟环境中同时管理多个相互关联的包无需逐个激活子项目即可统一安装依赖、运行测试和构建产物。读完本文你将掌握workspace.members/workspace.exclude/workspace.parallel等全部配置项的用法学会用hatch build --all一键打包所有成员并能组合测试矩阵、选项覆盖overrides搭建可落地的大型项目工作流。什么是 Workspace 环境在传统的单包项目中每个项目拥有独立的pyproject.toml和独立环境。但当项目演变为 monorepo多个相互依赖的包共存于一个仓库时逐个子包创建环境、手动解决包间的本地引用关系会非常繁琐。Hatch 的 Workspace 环境正是为此设计在环境配置中通过workspace.members声明成员Hatch 会将所有成员以可编辑editable方式自动安装进当前环境成员之间的互相依赖例如app依赖本地base也会被正确解析从而在一个环境内完成对整套包的统一开发与测试。从源码实现看工作区功能在 Hatch v1.16.0 引入其设计灵感来自 Cargo Workspaces参见 docs/history/hatch.md。基础配置在环境的pyproject.toml中通过workspace.members数组声明工作区成员[tool.hatch.envs.default] workspace.members [ packages/core, packages/utils, packages/cli ]这里的成员路径相对于**仓库根目录即项目根**解析。每个成员目录下必须存在自己的pyproject.toml否则 Hatch 会直接报错源码中通过os.path.isfile(member_path / pyproject.toml)校验见 src/hatch/env/plugin/interface.py。声明后工作区成员会自动作为可编辑包安装到环境中。从 src/hatch/env/plugin/interface.py 的实现看Hatch 会为每个成员构造形如-e member-name file:///.../member/path的可编辑依赖条目WorkspaceMember.get_editable_requirement返回f-e {self.name} {uri}与根项目一起加入环境依赖集合。使用 Glob 模式自动发现成员当成员数量多且命名规律时无需逐个列举直接用 glob 模式让 Hatch 自动发现[tool.hatch.envs.default] workspace.members [packages/*]Hatch 在解析成员时会对路径进行规范化处理先计算成员路径与项目根的公共前缀再在该前缀范围内做优化的 glob 搜索见 src/hatch/env/plugin/interface.py 中的find_members(shared_prefix, relative_path.split(os.sep))。这样即使模式包含../之类的相对跳转也能被正确解析——仓库历史中专门修复过共享路径前缀导致的成员识别问题见 docs/history/hatch.md。排除特定成员glob 模式会把所有匹配的目录都当作成员若某些包需要排除如实验性、未就绪的包用workspace.exclude指定排除模式[tool.hatch.envs.default] workspace.members [packages/*] workspace.exclude [packages/experimental*]源码中对每个发现的成员会依次匹配exclude模式基于fnmatch.fnmatch对相对路径和绝对路径的双重匹配见 src/hatch/env/plugin/interface.py命中的成员直接跳过。为成员指定额外特性Features不同成员可能需要不同的可选依赖。此时members中的条目可从字符串升级为内联表inline table通过path指定路径、features指定该成员要安装的[project.optional-dependencies]分组[tool.hatch.envs.default] workspace.members [ {path packages/core, features [dev]}, {path packages/utils, features [test, docs]}, packages/cli ]从实现上看src/hatch/env/plugin/interface.pyfeatures必须是字符串数组且不能为空、不能重复Hatch 会对 feature 名做规范化处理normalize_project_name后与成员自身的元数据关联最终通过resolve_extras解析出对应的可选依赖加入环境见Workspace.get_dependencies中对features.get(feature, [])的展开逻辑src/hatch/env/plugin/interface.py。仓库测试 tests/workspaces/test_config.py 验证了成员dev/test特性会被正确安装。不同环境使用不同的成员切片工作区配置是环境级的不同环境可以声明不同的成员集合天然支持“测试环境只装核心包、文档环境只装文档依赖”的分工[tool.hatch.envs.unit-tests] workspace.members [packages/core, packages/utils] scripts.test pytest tests/unit [tool.hatch.envs.integration-tests] workspace.members [packages/*] scripts.test pytest tests/integration [tool.hatch.envs.docs] workspace.members [ {path packages/core, features [docs]}, {path packages/utils, features [docs]} ]对应的集成测试见 tests/workspaces/test_config.pyunit-tests环境只创建core与utils两个成员integration-tests环境则包含packages/*下的全部包。通过hatch env create env-name即可按需创建各自独立的环境。一键构建所有成员发布整个工作区时无需逐个成员执行构建。使用build命令的--all等价于-a标志即可为工作区根项目和每一个工作区成员同时构建sdist与wheelhatch build --all行为要点与源码 src/hatch/cli/build/init.py 一一对应根项目先构建且无需列入成员列表。但如果顶层pyproject.toml没有定义project表、仅作为工作区配置的容器则根会被跳过源码通过app.project.defines_project判断即检查根pyproject.toml中是否存在project键见 src/hatch/project/core.py。成员从所选环境的workspace.members选项中发现若该环境未定义任何成员--all会直接报错中止。产物默认统一收拢到工作区根目录的dist目录DEFAULT_BUILD_DIRECTORY dist见 src/hatch/project/constants.py可直接交给twine upload dist/*发布。可通过位置参数指定产物输出目录hatch build --all out/artifacts--all标志的引入记录在 v1.18.0 发布说明中见 docs/blog/posts/release-hatch-1180.md配套的端到端测试见 tests/workspaces/test_config.py。与测试矩阵Test Matrices组合工作区配置可以与测试矩阵无缝组合矩阵为每个 Python 版本生成一个具体环境而每个生成的环境都会携带同样的工作区成员。典型用法是“全量包矩阵”与“仅核心包矩阵”并存[[tool.hatch.envs.test.matrix]] python [3.9, 3.10, 3.11, 3.12] [tool.hatch.envs.test] workspace.members [packages/*] dependencies [pytest, coverage] scripts.test pytest {args} [[tool.hatch.envs.test-core.matrix]] python [3.9, 3.10, 3.11, 3.12] [tool.hatch.envs.test-core] workspace.members [packages/core] dependencies [pytest, coverage] scripts.test pytest packages/core/tests {args}test环境在 4 个 Python 版本上测试全部成员test-core环境则只针对核心包做快速回归。仓库测试验证了矩阵环境下工作区成员配置可被正确展开见 tests/workspaces/test_config.py。矩阵变量与平台条件化成员进阶利用矩阵变量和平台条件可以精确控制“哪个环境装哪些成员”。例如成员路径中可直接引用矩阵变量{matrix:plugin}甚至可以通过overrides在特定条件下覆盖workspace.members[[tool.hatch.envs.test.matrix]] python [3.9, 3.11] [tool.hatch.envs.test] workspace.members [packages/core] [tool.hatch.envs.test.overrides] matrix.python.workspace.members [ { value packages/py311-only, if [3.11] } ][tool.hatch.envs.default] workspace.members [packages/core] [tool.hatch.envs.default.overrides] platform.linux.workspace.members [packages/linux-specific] platform.windows.workspace.members [packages/windows-specific]overrides还支持组合条件同时限定矩阵变量与平台如{ value ..., if [3.11], platform [linux] }。这三个场景在 tests/workspaces/test_config.py 中均有完整测试覆盖。关于overrides的通用语法可进一步参考 docs/config/environment/advanced.md。性能优化并行依赖解析当一个或多个成员的依赖需要动态解析例如成员的dependencies或optional-dependencies被标记为动态字段时Hatch 默认会并行解析各成员的依赖以加速环境创建[tool.hatch.envs.default] workspace.members [packages/*] workspace.parallel true对应实现见 src/hatch/env/plugin/interface.pyWorkspace.parallel默认值为true且必须是布尔类型否则抛TypeError并行解析基于concurrent.futures.ThreadPoolExecutor每个线程内通过self.env.app.status(fChecking workspace member: {member.name})输出进度workspace.parallel false则退化为串行逐个解析静态依赖成员has_static_dependencies即dependencies/optional-dependencies未列入project.dynamic见 src/hatch/project/core.py无需解析直接读取即可。在 CI 等对稳定性要求更高的场景可以显式关闭并行如后文 Monorepo 示例中的workspace.parallel false避免并发解析引入不确定性。完整示例一Monorepo 项目一份典型的 monorepo 完整配置覆盖默认开发环境、测试矩阵、独立 lint 环境与 CI 环境# Root pyproject.toml [project] name my-monorepo version 1.0.0 [tool.hatch.envs.default] workspace.members [packages/*] workspace.exclude [packages/experimental*] workspace.parallel true dependencies [pytest, black, ruff] [tool.hatch.envs.test] workspace.members [ {path packages/core, features [test]}, {path packages/utils, features [test]}, packages/cli ] dependencies [pytest, coverage, pytest-cov] scripts.test pytest --cov {args} [tool.hatch.envs.lint] detached true workspace.members [packages/*] dependencies [ruff, black, mypy] scripts.check [ruff check ., black --check ., mypy .] scripts.fmt [ruff check --fix ., black .] [[tool.hatch.envs.ci.matrix]] python [3.9, 3.10, 3.11, 3.12] [tool.hatch.envs.ci] template test workspace.parallel false # Disable for CI stability几个值得留意的设计点lint环境使用detached true使其自引用、跳过项目安装详见 docs/config/environment/overview.md同时通过workspace.members在共享环境里安装全部成员保证ruff check ./mypy .能覆盖整个仓库ci环境以test为模板template test继承其配置叠加矩阵后展开为 4 个 CI 环境并关闭并行解析保证稳定性scripts中的多条命令数组如scripts.check会按顺序执行。完整示例二带可选插件的库面向“核心库 若干可选插件”形态的库项目可定义不同粒度的环境——默认只装核心、full装全部插件、database-only只装数据库插件并用矩阵变量驱动“逐个插件测试”[tool.hatch.envs.default] workspace.members [core] dependencies [pytest] [tool.hatch.envs.full] workspace.members [ core, plugins/database, plugins/cache, plugins/auth ] dependencies [pytest, pytest-asyncio] [tool.hatch.envs.database-only] workspace.members [ core, {path plugins/database, features [postgresql, mysql]} ] [[tool.hatch.envs.plugin-test.matrix]] plugin [database, cache, auth] [tool.hatch.envs.plugin-test] workspace.members [ core, plugins/{matrix:plugin} ] scripts.test pytest plugins/{matrix:plugin}/tests {args}要点说明members路径支持上下文变量plugins/{matrix:plugin}会随矩阵变量展开为plugins/database、plugins/cache、plugins/auth三个具体成员——这正是源码中self.env.metadata.context.format(data)对路径做上下文格式化的效果见 src/hatch/env/plugin/interface.py插件的postgresql/mysql等可选依赖通过成员级features精准安装对应测试见 tests/workspaces/test_config.py。实战场景延伸微服务、文档与开发工作流除上述文档示例外仓库测试还覆盖了若干可直接迁移的实战形态全部位于 tests/workspaces/test_config.py微服务应用tests/workspaces/test_config.pyshared共享包 api/worker/frontend服务。default只装sharedapi环境额外装services/api含dev特性并注册scripts.dev uvicorn services.api.main:app --reloadintegration环境则一次性装入所有服务运行集成测试——环境各自通过skip-install true跳过根项目安装避免根项目无实际打包内容被重复安装。文档生成tests/workspaces/test_config.pydocs环境为每个成员的docs特性如sphinx、sphinx-rtd-theme提供依赖并执行mkdocs serve/mkdocs builddocs-api-only通过template docs继承并只保留core成员以--config-file mkdocs-api.yml输出仅 API 的文档站。统一开发环境 发布矩阵tests/workspaces/test_config.pydev环境一次装入packages/*全部成员与pytest/black/ruff/mypy/pre-commit工具链feature环境通过{env:FEATURE_PACKAGE}环境变量动态指定要测试的成员release环境以{matrix:package}遍历core、utils、cli分别执行python -m build与twine upload。这展示了成员路径中组合使用{matrix:...}与{env:...}上下文变量的灵活性。配置校验与常见错误Hatch 对工作区配置有严格的类型校验理解这些约束能帮你快速定位问题workspace必须是表tablemembers与exclude必须是数组见 src/hatch/env/utils.py 与 src/hatch/env/plugin/interface.pymembers中的每个条目必须是字符串或内联表内联表必须含path键path不能为空字符串features必须是字符串数组且元素不能为空、不能重复src/hatch/env/plugin/interface.py每个模式必须能派生出至少一个成员否则报 “No members could be derived from ...”派生的成员路径必须存在pyproject.toml且不能重复src/hatch/env/plugin/interface.pyworkspace.parallel必须是布尔值src/hatch/env/plugin/interface.pyhatch build --all要求所选环境定义了workspace.members否则中止src/hatch/cli/build/init.py。总结Hatch 的工作区环境把“多包 monorepo 的日常开发”收敛为一套统一的声明式配置workspace.members决定装哪些包workspace.exclude剔除不需要的包成员级features精确控制各包的可选依赖workspace.parallel加速解析而hatch build --all让“整个仓库一次构建发布”成为一条命令。配合矩阵、模板继承与overrides无论你是维护一个含十几个包的 monorepo还是“核心库 插件体系”都能用 docs/how-to/environment/workspace.md 所述的这套机制构建出简洁、可维护的开发与 CI 工作流。赞分享开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载相关推荐pixi workspace environment 命令完全指南用 add / list / remove 管理多环境工作区pixi workspace environment 命令完全指南用 add / list / remove 管理多环境工作区 pixi workspace开发工具CLI包管理器任务调度开发者必看CKIP BERT Tiny Chinese模型架构与代码实现原理开发者必看CKIP BERT Tiny Chinese模型架构与代码实现原理 想要在中文NLP项目中快速部署轻量级BERT模型吗CKIP BERT TinyDeepChat开发环境搭建pnpm workspace与monorepo配置DeepChat开发环境搭建pnpm workspace与monorepo配置 你还在为复杂项目的依赖管理头痛吗还在为多包项目的构建效率发愁吗本文将带你一AI Agent人工智能AI 应用桌面应用MCP Clients上一篇Hover Zoom性能优化指南如何避免内存泄漏和提升响应速度下一篇探索数据链接神器data-link-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Hatch 工作区（Workspace）环境配置完全指南：单环境管理多包 Monorepo
开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载Workspace 环境是 Hatch 面向 monorepo 与多包协同开发的核心能力它允许你在同一个虚拟环境中同时管理多个相互关联的包无需逐个激活子项目即可统一安装依赖、运行测试和构建产物。读完本文你将掌握workspace.members/workspace.exclude/workspace.parallel等全部配置项的用法学会用hatch build --all一键打包所有成员并能组合测试矩阵、选项覆盖overrides搭建可落地的大型项目工作流。什么是 Workspace 环境在传统的单包项目中每个项目拥有独立的pyproject.toml和独立环境。但当项目演变为 monorepo多个相互依赖的包共存于一个仓库时逐个子包创建环境、手动解决包间的本地引用关系会非常繁琐。Hatch 的 Workspace 环境正是为此设计在环境配置中通过workspace.members声明成员Hatch 会将所有成员以可编辑editable方式自动安装进当前环境成员之间的互相依赖例如app依赖本地base也会被正确解析从而在一个环境内完成对整套包的统一开发与测试。从源码实现看工作区功能在 Hatch v1.16.0 引入其设计灵感来自 Cargo Workspaces参见 docs/history/hatch.md。基础配置在环境的pyproject.toml中通过workspace.members数组声明工作区成员[tool.hatch.envs.default] workspace.members [ packages/core, packages/utils, packages/cli ]这里的成员路径相对于**仓库根目录即项目根**解析。每个成员目录下必须存在自己的pyproject.toml否则 Hatch 会直接报错源码中通过os.path.isfile(member_path / pyproject.toml)校验见 src/hatch/env/plugin/interface.py。声明后工作区成员会自动作为可编辑包安装到环境中。从 src/hatch/env/plugin/interface.py 的实现看Hatch 会为每个成员构造形如-e member-name file:///.../member/path的可编辑依赖条目WorkspaceMember.get_editable_requirement返回f-e {self.name} {uri}与根项目一起加入环境依赖集合。使用 Glob 模式自动发现成员当成员数量多且命名规律时无需逐个列举直接用 glob 模式让 Hatch 自动发现[tool.hatch.envs.default] workspace.members [packages/*]Hatch 在解析成员时会对路径进行规范化处理先计算成员路径与项目根的公共前缀再在该前缀范围内做优化的 glob 搜索见 src/hatch/env/plugin/interface.py 中的find_members(shared_prefix, relative_path.split(os.sep))。这样即使模式包含../之类的相对跳转也能被正确解析——仓库历史中专门修复过共享路径前缀导致的成员识别问题见 docs/history/hatch.md。排除特定成员glob 模式会把所有匹配的目录都当作成员若某些包需要排除如实验性、未就绪的包用workspace.exclude指定排除模式[tool.hatch.envs.default] workspace.members [packages/*] workspace.exclude [packages/experimental*]源码中对每个发现的成员会依次匹配exclude模式基于fnmatch.fnmatch对相对路径和绝对路径的双重匹配见 src/hatch/env/plugin/interface.py命中的成员直接跳过。为成员指定额外特性Features不同成员可能需要不同的可选依赖。此时members中的条目可从字符串升级为内联表inline table通过path指定路径、features指定该成员要安装的[project.optional-dependencies]分组[tool.hatch.envs.default] workspace.members [ {path packages/core, features [dev]}, {path packages/utils, features [test, docs]}, packages/cli ]从实现上看src/hatch/env/plugin/interface.pyfeatures必须是字符串数组且不能为空、不能重复Hatch 会对 feature 名做规范化处理normalize_project_name后与成员自身的元数据关联最终通过resolve_extras解析出对应的可选依赖加入环境见Workspace.get_dependencies中对features.get(feature, [])的展开逻辑src/hatch/env/plugin/interface.py。仓库测试 tests/workspaces/test_config.py 验证了成员dev/test特性会被正确安装。不同环境使用不同的成员切片工作区配置是环境级的不同环境可以声明不同的成员集合天然支持“测试环境只装核心包、文档环境只装文档依赖”的分工[tool.hatch.envs.unit-tests] workspace.members [packages/core, packages/utils] scripts.test pytest tests/unit [tool.hatch.envs.integration-tests] workspace.members [packages/*] scripts.test pytest tests/integration [tool.hatch.envs.docs] workspace.members [ {path packages/core, features [docs]}, {path packages/utils, features [docs]} ]对应的集成测试见 tests/workspaces/test_config.pyunit-tests环境只创建core与utils两个成员integration-tests环境则包含packages/*下的全部包。通过hatch env create env-name即可按需创建各自独立的环境。一键构建所有成员发布整个工作区时无需逐个成员执行构建。使用build命令的--all等价于-a标志即可为工作区根项目和每一个工作区成员同时构建sdist与wheelhatch build --all行为要点与源码 src/hatch/cli/build/init.py 一一对应根项目先构建且无需列入成员列表。但如果顶层pyproject.toml没有定义project表、仅作为工作区配置的容器则根会被跳过源码通过app.project.defines_project判断即检查根pyproject.toml中是否存在project键见 src/hatch/project/core.py。成员从所选环境的workspace.members选项中发现若该环境未定义任何成员--all会直接报错中止。产物默认统一收拢到工作区根目录的dist目录DEFAULT_BUILD_DIRECTORY dist见 src/hatch/project/constants.py可直接交给twine upload dist/*发布。可通过位置参数指定产物输出目录hatch build --all out/artifacts--all标志的引入记录在 v1.18.0 发布说明中见 docs/blog/posts/release-hatch-1180.md配套的端到端测试见 tests/workspaces/test_config.py。与测试矩阵Test Matrices组合工作区配置可以与测试矩阵无缝组合矩阵为每个 Python 版本生成一个具体环境而每个生成的环境都会携带同样的工作区成员。典型用法是“全量包矩阵”与“仅核心包矩阵”并存[[tool.hatch.envs.test.matrix]] python [3.9, 3.10, 3.11, 3.12] [tool.hatch.envs.test] workspace.members [packages/*] dependencies [pytest, coverage] scripts.test pytest {args} [[tool.hatch.envs.test-core.matrix]] python [3.9, 3.10, 3.11, 3.12] [tool.hatch.envs.test-core] workspace.members [packages/core] dependencies [pytest, coverage] scripts.test pytest packages/core/tests {args}test环境在 4 个 Python 版本上测试全部成员test-core环境则只针对核心包做快速回归。仓库测试验证了矩阵环境下工作区成员配置可被正确展开见 tests/workspaces/test_config.py。矩阵变量与平台条件化成员进阶利用矩阵变量和平台条件可以精确控制“哪个环境装哪些成员”。例如成员路径中可直接引用矩阵变量{matrix:plugin}甚至可以通过overrides在特定条件下覆盖workspace.members[[tool.hatch.envs.test.matrix]] python [3.9, 3.11] [tool.hatch.envs.test] workspace.members [packages/core] [tool.hatch.envs.test.overrides] matrix.python.workspace.members [ { value packages/py311-only, if [3.11] } ][tool.hatch.envs.default] workspace.members [packages/core] [tool.hatch.envs.default.overrides] platform.linux.workspace.members [packages/linux-specific] platform.windows.workspace.members [packages/windows-specific]overrides还支持组合条件同时限定矩阵变量与平台如{ value ..., if [3.11], platform [linux] }。这三个场景在 tests/workspaces/test_config.py 中均有完整测试覆盖。关于overrides的通用语法可进一步参考 docs/config/environment/advanced.md。性能优化并行依赖解析当一个或多个成员的依赖需要动态解析例如成员的dependencies或optional-dependencies被标记为动态字段时Hatch 默认会并行解析各成员的依赖以加速环境创建[tool.hatch.envs.default] workspace.members [packages/*] workspace.parallel true对应实现见 src/hatch/env/plugin/interface.pyWorkspace.parallel默认值为true且必须是布尔类型否则抛TypeError并行解析基于concurrent.futures.ThreadPoolExecutor每个线程内通过self.env.app.status(fChecking workspace member: {member.name})输出进度workspace.parallel false则退化为串行逐个解析静态依赖成员has_static_dependencies即dependencies/optional-dependencies未列入project.dynamic见 src/hatch/project/core.py无需解析直接读取即可。在 CI 等对稳定性要求更高的场景可以显式关闭并行如后文 Monorepo 示例中的workspace.parallel false避免并发解析引入不确定性。完整示例一Monorepo 项目一份典型的 monorepo 完整配置覆盖默认开发环境、测试矩阵、独立 lint 环境与 CI 环境# Root pyproject.toml [project] name my-monorepo version 1.0.0 [tool.hatch.envs.default] workspace.members [packages/*] workspace.exclude [packages/experimental*] workspace.parallel true dependencies [pytest, black, ruff] [tool.hatch.envs.test] workspace.members [ {path packages/core, features [test]}, {path packages/utils, features [test]}, packages/cli ] dependencies [pytest, coverage, pytest-cov] scripts.test pytest --cov {args} [tool.hatch.envs.lint] detached true workspace.members [packages/*] dependencies [ruff, black, mypy] scripts.check [ruff check ., black --check ., mypy .] scripts.fmt [ruff check --fix ., black .] [[tool.hatch.envs.ci.matrix]] python [3.9, 3.10, 3.11, 3.12] [tool.hatch.envs.ci] template test workspace.parallel false # Disable for CI stability几个值得留意的设计点lint环境使用detached true使其自引用、跳过项目安装详见 docs/config/environment/overview.md同时通过workspace.members在共享环境里安装全部成员保证ruff check ./mypy .能覆盖整个仓库ci环境以test为模板template test继承其配置叠加矩阵后展开为 4 个 CI 环境并关闭并行解析保证稳定性scripts中的多条命令数组如scripts.check会按顺序执行。完整示例二带可选插件的库面向“核心库 若干可选插件”形态的库项目可定义不同粒度的环境——默认只装核心、full装全部插件、database-only只装数据库插件并用矩阵变量驱动“逐个插件测试”[tool.hatch.envs.default] workspace.members [core] dependencies [pytest] [tool.hatch.envs.full] workspace.members [ core, plugins/database, plugins/cache, plugins/auth ] dependencies [pytest, pytest-asyncio] [tool.hatch.envs.database-only] workspace.members [ core, {path plugins/database, features [postgresql, mysql]} ] [[tool.hatch.envs.plugin-test.matrix]] plugin [database, cache, auth] [tool.hatch.envs.plugin-test] workspace.members [ core, plugins/{matrix:plugin} ] scripts.test pytest plugins/{matrix:plugin}/tests {args}要点说明members路径支持上下文变量plugins/{matrix:plugin}会随矩阵变量展开为plugins/database、plugins/cache、plugins/auth三个具体成员——这正是源码中self.env.metadata.context.format(data)对路径做上下文格式化的效果见 src/hatch/env/plugin/interface.py插件的postgresql/mysql等可选依赖通过成员级features精准安装对应测试见 tests/workspaces/test_config.py。实战场景延伸微服务、文档与开发工作流除上述文档示例外仓库测试还覆盖了若干可直接迁移的实战形态全部位于 tests/workspaces/test_config.py微服务应用tests/workspaces/test_config.pyshared共享包 api/worker/frontend服务。default只装sharedapi环境额外装services/api含dev特性并注册scripts.dev uvicorn services.api.main:app --reloadintegration环境则一次性装入所有服务运行集成测试——环境各自通过skip-install true跳过根项目安装避免根项目无实际打包内容被重复安装。文档生成tests/workspaces/test_config.pydocs环境为每个成员的docs特性如sphinx、sphinx-rtd-theme提供依赖并执行mkdocs serve/mkdocs builddocs-api-only通过template docs继承并只保留core成员以--config-file mkdocs-api.yml输出仅 API 的文档站。统一开发环境 发布矩阵tests/workspaces/test_config.pydev环境一次装入packages/*全部成员与pytest/black/ruff/mypy/pre-commit工具链feature环境通过{env:FEATURE_PACKAGE}环境变量动态指定要测试的成员release环境以{matrix:package}遍历core、utils、cli分别执行python -m build与twine upload。这展示了成员路径中组合使用{matrix:...}与{env:...}上下文变量的灵活性。配置校验与常见错误Hatch 对工作区配置有严格的类型校验理解这些约束能帮你快速定位问题workspace必须是表tablemembers与exclude必须是数组见 src/hatch/env/utils.py 与 src/hatch/env/plugin/interface.pymembers中的每个条目必须是字符串或内联表内联表必须含path键path不能为空字符串features必须是字符串数组且元素不能为空、不能重复src/hatch/env/plugin/interface.py每个模式必须能派生出至少一个成员否则报 “No members could be derived from ...”派生的成员路径必须存在pyproject.toml且不能重复src/hatch/env/plugin/interface.pyworkspace.parallel必须是布尔值src/hatch/env/plugin/interface.pyhatch build --all要求所选环境定义了workspace.members否则中止src/hatch/cli/build/init.py。总结Hatch 的工作区环境把“多包 monorepo 的日常开发”收敛为一套统一的声明式配置workspace.members决定装哪些包workspace.exclude剔除不需要的包成员级features精确控制各包的可选依赖workspace.parallel加速解析而hatch build --all让“整个仓库一次构建发布”成为一条命令。配合矩阵、模板继承与overrides无论你是维护一个含十几个包的 monorepo还是“核心库 插件体系”都能用 docs/how-to/environment/workspace.md 所述的这套机制构建出简洁、可维护的开发与 CI 工作流。赞分享开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载相关推荐pixi workspace environment 命令完全指南用 add / list / remove 管理多环境工作区pixi workspace environment 命令完全指南用 add / list / remove 管理多环境工作区 pixi workspace开发工具CLI包管理器任务调度开发者必看CKIP BERT Tiny Chinese模型架构与代码实现原理开发者必看CKIP BERT Tiny Chinese模型架构与代码实现原理 想要在中文NLP项目中快速部署轻量级BERT模型吗CKIP BERT TinyDeepChat开发环境搭建pnpm workspace与monorepo配置DeepChat开发环境搭建pnpm workspace与monorepo配置 你还在为复杂项目的依赖管理头痛吗还在为多包项目的构建效率发愁吗本文将带你一AI Agent人工智能AI 应用桌面应用MCP Clients上一篇Hover Zoom性能优化指南如何避免内存泄漏和提升响应速度下一篇探索数据链接神器data-link-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
