Poetry配置无效：'group'未预期的属性

WARNING

关键错误信息
RuntimeError: The Poetry configuration is invalid: Additional properties are not allowed ('group' was unexpected)
当看到此错误时，说明您的Poetry版本已过时

问题原因

此错误直接指向Poetry版本兼容性问题：

• 项目中的pyproject.toml使用了依赖分组(group)功能（仅Poetry 1.2.0+支持）
• 您本地的Poetry版本低于1.2.0（通常是1.1.x版本）
• 旧版本Poetry无法解析新增配置项，引发验证失败

依赖分组功能示例（新版本语法）：

[tool.poetry.group.dev]  # 旧版Poetry无法识别此语法
optional = false

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"

解决方案

方法一：升级Poetry（推荐）

适用于通过pip安装的Poetry

Linux/macOS

# 卸载旧版本
rm -rf ~/.poetry   # 移除Poetry配置缓存

# 升级核心库
pip install --upgrade pip setuptools

# 安装最新Poetry
pip install --user poetry -U

Windows PowerShell

# 清除旧数据
Remove-Item -Recurse -Force $env:APPDATA\pypoetry

# 更新安装工具
python -m pip install --upgrade pip setuptools

# 安装最新版
pip install --user poetry -U

验证

poetry --version  # 应显示 Poetry (version 1.8.x)
poetry install        # 重新安装项目依赖

方法二：使用pipx安装（官方推荐）

适用全新安装或解决环境冲突

1. 安装pipx（若未安装）

sudo apt update
sudo apt install pipx
pipx ensurepath

2. 通过pipx安装Poetry

pipx install poetry  # 隔离环境安装

3. 验证安装

which poetry    # 应显示pipx路径
poetry --version

方法三：解决环境冲突问题

特别针对conda/anaconda用户

conda deactivate  # 退出可能冲突的conda环境
poetry install     # 在基础环境重试

操作后必做

强制重建依赖锁
执行以下操作保证依赖解析正确：

rm poetry.lock      # 删除旧锁文件
poetry install --no-root  # 重新生成锁文件

补充：解决相关错误 data.source[0] must not contain {'secondary'}

若遇到此错误同样源于版本不兼容：

1. 从pyproject.toml中移除所有secondary = true
2. 删除poetry.lock文件
3. 按上述方法升级Poetry
4. 执行poetry install --no-root

附加说明

版本选择建议

环境	推荐操作
多环境项目	pipx install poetry
Docker容器	pip install poetry=1.8.3
Windows系统	官方安装脚本+PowerShell执行

疑难排查

1. 持续出现错误时运行：

   poetry config --list  # 检查配置状态
   poetry debug info     # 显示环境信息

2. 项目包含旧版配置时：
   • 将requires = ["poetry-core>=1.2.0"]加入pyproject.toml
   • 删除项目虚拟机（rm -rf .venv）后重装

TIP

官方升级参考
详细迁移指南可查阅：Poetry 1.2发布公告
对于团队项目，建议在CONTRIBUTING.md中声明Poetry版本要求

遵循上述操作后，依赖分组功能即可正常使用：

[tool.poetry.group.lint]
optional = true

[tool.poetry.group.lint.dependencies]
flake8 = ">=6.1.0"
black = { version = "23.7.0", allow-prereleases = true }