Visual Studio Code中PyLance无法识别Poetry虚拟环境依赖问题排查

使用Poetry管理Python项目，通过poetry install和pyproject.toml流程创建虚拟环境后，Visual Studio Code的PyLance在Jupyter Notebook中无法识别项目第三方依赖库模块，报错Import "xxx" could not be resolved Pylance (reportMissingImports)。但Notebook可正常运行，说明虚拟环境配置无误，Python标准库、项目自身模块可被正常识别。

相关Python语言服务器日志如下：

2024-03-01 10:15:40.628 [info] [Info  - 10:15:40] (28928) Starting service instance "trade-executor"
2024-03-01 10:15:40.656 [info] [Info  - 10:15:40] (28928) Setting pythonPath for service "trade-executor": "/Users/moo/code/ts/trade-executor"
2024-03-01 10:15:40.657 [info] [Info  - 10:15:40] (28928) Setting environmentName for service "trade-executor": "3.10.13 (trade-executor-8Oz1GdY1-py3.10 venv)"
2024-03-01 10:15:40.657 [info] [Info  - 10:15:40] (28928) Loading pyproject.toml file at /Users/moo/code/ts/trade-executor/pyproject.toml
2024-03-01 10:15:40.657 [info] [Info  - 10:15:40] (28928) Pyproject file "/Users/moo/code/ts/trade-executor/pyproject.toml" has no "[tool.pyright]" section.
2024-03-01 10:15:41.064 [info] [Info  - 10:15:41] (28928) Found 763 source files
2024-03-01 10:15:41.158 [info] [Info  - 10:15:41] (28928) Background analysis(4) root directory: file:///Users/moo/.vscode/extensions/ms-python.vscode-pylance-2024.2.2/dist
2024-03-01 10:15:41.158 [info] [Info  - 10:15:41] (28928) Background analysis(4) started
2024-03-01 10:15:41.411 [info] [Info  - 10:15:41] (28928) Indexer background runner(5) root directory: file:///Users/moo/.vscode/extensions/ms-python.vscode-pylance-2024.2.2/dist (index)
2024-03-01 10:15:41.411 [info] [Info  - 10:15:41] (28928) Indexing(5) started
2024-03-01 10:15:41.662 [info] [Info  - 10:15:41] (28928) scanned(5) 1 files over 1 exec env
2024-03-01 10:15:42.326 [info] [Info  - 10:15:42] (28928) indexed(5) 1 files over 1 exec

2024-03-03 19:36:56.784 [info] [Info  - 19:36:56] (41658) Pylance language server 2024.2.2 (pyright version 1.1.348, commit cfb1de0c) starting
2024-03-03 19:36:56.789 [info] [Info  - 19:36:56] (41658) Server root directory: file:///Users/moo/.vscode/extensions/ms-python.vscode-pylance-2024.2.2/dist
2024-03-03 19:36:56.789 [info] [Info  - 19:36:56] (41658) Starting service instance "trade-executor"
2024-03-03 19:36:57.091 [info] [Info  - 19:36:57] (41658) Setting pythonPath for service "trade-executor": "/Users/moo/Library/Caches/pypoetry/virtualenvs/trade-executor-8Oz1GdY1-py3.10/bin/python"
2024-03-03 19:36:57.093 [info] [Info  - 19:36:57] (41658) Setting environmentName for service "trade-executor": "3.10.13 (trade-executor-8Oz1GdY1-py3.10 venv)"
2024-03-03 19:36:57.096 [info] [Info  - 19:36:57] (41658) Loading pyproject.toml file at /Users/moo/code/ts/trade-executor/pyproject.toml

• 确认Jupyter内核与虚拟环境绑定
  打开Notebook，查看右上角内核名称，确认是否为Poetry创建的trade-executor-8Oz1GdY1-py3.10。若不一致，执行以下命令将Poetry虚拟环境注册为Jupyter内核：

  poetry run python -m ipykernel install --user --name=trade-executor
  

  注册完成后切换Notebook内核至该环境。

• 强制PyLance重新索引依赖
  打开VS Code命令面板（Ctrl/Cmd+Shift+P），执行Python: Restart Language Server重启Pylance服务；或执行Developer: Reload Window重载VS Code窗口，触发依赖重新扫描。

• 手动指定PyLance依赖搜索路径

  1. 获取Poetry虚拟环境的site-packages路径：

     poetry run python -c "import site; print(site.getsitepackages()[0])"
     

  2. 在项目根目录创建.vscode/settings.json，添加如下配置（替换为上一步得到的路径）：

     {
       "python.analysis.extraPaths": [
         "/Users/moo/Library/Caches/pypoetry/virtualenvs/trade-executor-8Oz1GdY1-py3.10/lib/python3.10/site-packages"
       ]
     }
     

• 补充pyproject.toml的Pyright配置
  在pyproject.toml中添加[tool.pyright]区块，帮助PyLance自动识别虚拟环境依赖：

  [tool.pyright]
  extraPaths = ["${env:VIRTUAL_ENV}/lib/python3.10/site-packages"]
  

• 验证虚拟环境依赖完整性
  执行poetry run pip list确认第三方依赖已全部安装；执行poetry run python -c "import xxx"（替换xxx为报错的依赖库），验证虚拟环境中可正常导入该库。

内容的提问来源于stack exchange，提问作者Mikko Ohtamaa