离线安装vscode扩展必须使用官方发布的.vsix文件，而非.zip包或源码目录；应通过拖拽到编辑区或code --install-extension命令安装，并确保版本兼容、依赖完整、未被策略禁用。
离线安装 VSCode 扩展必须用 .vsix 文件，不是 .zip 或源码目录
VSCode 离线安装只认官方打包的 .vsix 格式，直接拖拽文件进窗口或用命令行 code --install-extension xxx.vsix 才生效。常见错误是把 GitHub 仓库 clone 下来、解压后试图“加载已解压的扩展”——这仅对开发调试有效，且需含 package.json 和正确入口，普通用户几乎必失败。
获取合法 .vsix 的可靠路径：在有网机器上打开 VSCode → 访问扩展市场 → 搜索目标扩展（如 esbenp.prettier-vscode）→ 点击右下角「Download Extension」链接（页面 URL 含 /item?itemName=xxx 时，把 item 改成 vsix 即可得直链）；或用官方 CLI 工具 vsce package（需提前装 Node.js 和 vsce）。
- 注意扩展依赖：比如
docsmsft.python依赖ms-python.vscode-pylance，离线时两个.vsix都得装，且安装顺序无强制要求，但启用前建议先装依赖项 - 版本兼容性要核对：
.vsix文件名里常含 VSCode 版本约束（如-v1.85.0），低于该版本可能提示 “This extension is not compatible with your version of VS Code” - 装完不显示？检查是否被工作区设置禁用：
"extensions.ignoreRecommendations": true不影响安装，但可能掩盖启用状态；手动在扩展面板点「启用」图标
AutoDocstring 是目前最稳的 Python 自动文档字符串生成器
想让 VSCode 在函数光标处按 Ctrl+Alt+D（Windows/Linux）或 Cmd+Alt+D（macOS）自动生成 Google/NumPy/Napoleon 风格 docstring，AutoDocstring（作者 njpwerner）仍是实测兼容性最好、不崩不卡的选择。它不依赖 LSP，纯客户端逻辑，对老旧 Python 环境（如 3.6+）也友好。
- 触发前提：光标必须严格位于
def行末尾或函数体第一行（空行或注释不算），否则快捷键无响应 - 模板可配置：在
settings.json中加"autoDocstring.docstringFormat": "google"，可选值为"google"、"numpy"、"sphinx" - 别和
Python Docstring Generator（同名不同作者）混淆——后者已多年未更新，VSCode 1.80+ 起频繁报Cannot read properties of undefined (reading 'document') - 若生成内容为空，大概率是没识别出参数：确认函数定义语法规范（无解构赋值、无星号表达式混用），例如
def foo(a: int, *args, **kwargs):可识别，但def foo((a, b)):会失败
用 pydoc-markdown + Markdown Preview Enhanced 实现离线文档预览
VSCode 内置的文档预览只支持 hover 提示，真要生成完整 API 文档页并离线浏览，得组合命令行工具与本地渲染。推荐 pydoc-markdown（Python 原生，支持 __all__ 过滤和模块分组）搭配 VSCode 插件 shd101wyy.markdown-preview-enhanced（支持数学公式、图表、TOC 自动折叠）。
- 安装步骤（离线环境）：
pip install pydoc-markdown-3.12.0-py3-none-any.whl（提前下载对应 Python 版本的 wheel 包）；VSCode 扩展用.vsix安装shd101wyy.markdown-preview-enhanced - 生成命令示例：
pydoc-markdown -I ./src -m mypackage -o docs/api.md --render-toc，其中-I指定源码路径，-m是模块名（非路径），--render-toc启用目录 - 关键避坑：
pydoc-markdown默认不递归扫描子包，需显式加--include-modules或在配置文件中设loaders: [{type: "python", modules: ["mypackage"]}] - 预览时右键
api.md→ 「Open Preview to the Side」，若公式不渲染，检查插件设置中"markdown-preview-enhanced.enableExtendedSyntax": true
离线环境里别碰 robertohuertasm.vscode-icons 的自动更新
这个图标主题插件虽小，但在离线时若开启自动检查更新（默认开启），每次启动 VSCode 都会在后台发起 HTTP 请求，导致界面卡顿 2–3 秒，并在开发者工具 Console 中反复报错：getaddrinfo ENOTFOUND marketplace.visualstudio.com。这不是崩溃，但极其干扰使用节奏。
解决方式极简：打开 VSCode 设置（Ctrl+,），搜索 extensions.autoCheckUpdates，把它设为 false；或者直接编辑 settings.json 加一行："extensions.autoCheckUpdates": false。
- 此设置全局生效，不影响已安装扩展的功能，只停掉所有扩展的联网检查
- 如果只想关掉图标插件的更新，目前 VSCode 不支持 per-extension 控制，只能全局关
- 顺带一提：
vscode-icons的 SVG 图标资源全内置在.vsix里，离线使用完全正常，无需额外操作
pydoc-markdown 4.x 要求 Python 3.8+，而很多离线生产环境还跑着 3.6；这时候宁可降级用 3.12.x，也不要强行升级解释器。
