解决uv工具在Windows下模块导入问题的技术方案

问题背景

在使用astral-sh/uv工具时，开发者发现了一个跨平台兼容性问题：在macOS系统下，通过uv run scripts/test.py --project .命令可以正常执行脚本并导入项目中的模块，但在Windows系统下，同样的操作却会导致ModuleNotFoundError: No module named 'app'错误。

问题本质

这个问题实际上反映了Python模块导入机制在不同操作系统下的表现差异。当从子目录运行脚本时，Python解释器会根据当前工作目录来解析模块导入路径。在macOS/Linux系统下，--project .参数能够正确设置模块搜索路径，但在Windows环境下，这种设置似乎未能生效。

解决方案

经过技术验证，最可靠的解决方案是通过修改pyproject.toml配置文件来明确定义模块结构：

1. 首先，在pyproject.toml中添加项目脚本定义：

[project.scripts]
test = "scripts.test:main"

2. 然后配置构建系统相关信息：

[build-system]
requires = ["uv_build"]
build-backend = "uv_build"

[tool.uv.build-backend]
module-root = ""
module-name = "app"

3. 在脚本中将主逻辑放入main函数：

def main():
    from app.foo import bar
    bar()

配置完成后，只需简单地执行uv run test命令，即可跨平台地正确运行脚本并解析模块依赖。

技术原理

这种解决方案之所以有效，是因为它：

1. 通过pyproject.toml明确定义了项目的模块结构和入口点
2. 使用uv_build作为构建后端，确保模块解析的一致性
3. 将脚本执行逻辑封装在函数中，提高了代码的可维护性
4. 完全遵循Python打包标准，确保了跨平台兼容性

最佳实践建议

1. 对于任何使用uv工具的项目，建议从一开始就采用这种配置方式
2. 保持venv虚拟环境位于项目根目录
3. 统一使用相对导入方式编写代码
4. 在团队开发中，确保所有成员使用相同的项目结构配置

这种方法不仅解决了Windows下的模块导入问题，还使项目结构更加规范，便于维护和协作开发。