VSCode 不解析或执行 docstring，仅作为字符串字面量存在；Python Docstring Generator 仅在编辑阶段根据函数签名生成模板，不影响运行逻辑；运行期解析需依赖 inspect、Sphinx 等第三方库。
VSCode 本身不解析或执行 docstring，运行 Python 时也不会“读取”或“验证”你写的 docstring——它只是字符串字面量。所谓“自动生成”和“运行期解析测试”是两个完全独立的环节，混在一起容易误判问题根源。
Python Docstring Generator 不参与运行期行为
这个扩展只在编辑阶段起作用：光标停在函数体第一行，输入 """ 回车，它就根据当前函数签名（参数名、类型提示、返回值）生成一段字符串模板。生成后的内容和普通字符串无异，Python 解释器运行时根本不会检查它是否规范、字段是否缺失、缩进是否对齐。
- 生成的 docstring 不影响代码执行逻辑，哪怕写成
"""hello world"""或留空，程序照样跑 - 运行期想“解析” docstring，得靠第三方库（如
pydoc、sphinx.ext.napoleon、inspect.getdoc()），不是 VSCode 或 Python 解释器默认做的事 - 如果你发现
help(fn)显示内容不对，问题一定出在函数定义位置或字符串内容本身，而非扩展没“生效”
触发 docstring 生成失败的三个典型位置错误
很多人按了回车没反应，不是扩展坏了，而是光标没放对地方。VSCode 的语言服务只在特定 AST 节点上下文里激活补全逻辑。
- 光标必须在函数定义下方、且处于**函数体内部的第一行有效缩进位置**（比如
def foo():下一行，缩进 4 空格处） - 不能放在函数签名行末尾（如
def foo(a, b):|），也不能放在函数外部或注释行里 - 函数必须有完整签名：至少要有
def关键字 + 函数名 + 括号；如果用了lambda或赋值式函数（fn = lambda x: x），扩展基本无法识别
运行期测试 docstring 是否可被正确提取
要验证你生成的 docstring 在运行时是否可用，别依赖 VSCode 预览，直接在 Python 终端里试：
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
import inspect
def example(x: int) -> str:
"""Example function.
Args:
x: input number
Returns:
string representation
"""
return str(x)
print(inspect.getdoc(example))
输出非 None 才算真正生效。注意：
-
inspect.getdoc()会自动 strip 开头/结尾空白，但不会修复格式错误（比如把Args:写成Arguments:不影响提取，只是后续工具如 Sphinx 可能不识别） - 如果用的是 NumPy 风格，确保
python.analysis.extraPaths已设（尤其跨包引用类型时），否则类型提示可能解析失败，导致生成的 docstring 缺类型字段 - 类型提示写在参数上（
x: int）比写在 docstring 里更可靠；运行期解析工具优先读类型提示，其次才 fallback 到 docstring 字段
别混淆 python.docstringGenerator.style 和 autoDocstring.docstringFormat
这两个配置项对应不同扩展，混用会导致设置无效甚至快捷键冲突。
- 装的是
njpwerner.autodocstring（即 AutoDocstring）？用autoDocstring.docstringFormat控制风格，快捷键是输入"""后回车 - 装的是
njpwerner.python-docstring-generator（旧名，现市场已下架）或类似 ID 的“Python Docstring Generator”？用python.docstringGenerator.style，快捷键是Ctrl+Shift+2（Win/Linux）或Cmd+Shift+2（macOS） - 两者不能共存；若同时启用，常出现快捷键失效、生成内容错乱（比如参数名变成
arg1而非真实名）
真正容易被忽略的是：docstring 是代码的一部分，不是元数据。它能否被运行期工具利用，取决于你写的字符串是否符合约定格式，而不是 VSCode “生成”动作本身有多智能。
