VS Code中Pylance无法解析共享文件夹UNC路径下Python包的导入问题

问题场景 #

• 已将共享文件夹的UNC路径添加至PYTHONPATH环境变量
• Python代码可正常执行from mail import Mail语句，但Pylance报错：Import "mail" could not be resolved Pylance(reportMissingImports)
• 将包复制到本地文件夹并添加路径至PYTHONPATH后，Pylance可正常解析导入，确认问题源于UNC路径的识别

解决方案 #

1. 直接在VS Code设置中添加UNC路径到分析路径 #

打开VS Code设置（快捷键Ctrl+,），搜索python.analysis.extraPaths，点击「编辑 in settings.json」，将UNC路径转义后添加进去（JSON中反斜杠需用双反斜杠，因此UNC路径的\\要写成\\\\）：

{
    "python.analysis.extraPaths": [
        "\\\\your-server\\shared-folder\\python-packages"
    ]
}

2. 用符号链接将UNC路径映射为本地盘符 #

以管理员权限打开命令提示符，执行以下命令创建目录符号链接，把UNC路径映射到本地虚拟目录：

mklink /D C:\shared-py-packages \\your-server\shared-folder\python-packages

之后将C:\shared-py-packages添加到PYTHONPATH，Pylance即可正常识别该路径下的包。

3. 检查Pylance工作区配置 #

确认工作区的.vscode/settings.json未覆盖全局PYTHONPATH设置，同时确保python.analysis.useLibraryCodeForTypes设置为true（默认值，若被修改可能影响路径识别逻辑）。

原因说明 #

Python解释器本身支持UNC路径的解析，但Pylance的静态分析逻辑在处理PYTHONPATH中的UNC路径时存在兼容性问题，通过直接指定分析路径或映射为本地路径的方式可绕过该限制。

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