quarto 支持从命令行传入参数并在文档中使用，但 python 环境下需显式声明参数变量并添加 #| tags: [parameters] 元数据标记，否则变量无法被自动注入执行上下文。
quarto 支持从命令行传入参数并在文档中使用，但 python 环境下需显式声明参数变量并添加 #| tags: [parameters] 元数据标记，否则变量无法被自动注入执行上下文。
在 Quarto 中为 Python 渲染器（如 Jupyter）传递命令行参数时，不能直接像 R 环境那样通过 params$foo 访问，也不支持隐式变量注入。必须通过一个特殊的、带元数据标记的代码块显式声明参数变量及其默认值，Quarto 才会在渲染时将其替换为命令行传入的值。
✅ 正确用法：声明 + 标记 + 使用
以下是最小可运行示例（test.qmd）：
--- title: "Test File" format: html html: embed-resources: true execute: echo: false jupyter: python3 ---
#| tags: [parameters] foo = 5 # ← 默认值；会被命令行 -P foo:123 覆盖
# 使用参数（无需前缀，直接引用变量名）
print(f"Received parameter 'foo' = {foo}")
print(f"Type: {type(foo)}") # 注意：命令行传入的数字默认为 int，字符串则为 str然后通过 CLI 渲染：
quarto render test.qmd -P foo:42 --output test_cmd_out.html
输出 HTML 中将显示：
立即学习“Python免费学习笔记（深入）”；
Received parameter 'foo' = 42 Type: <class 'int'>
⚠️ 关键注意事项
- #| tags: [parameters] 是必需的：该元数据标记告诉 Quarto 将此代码块视为“参数声明区”，只有带此标记的变量才会被命令行参数覆盖。
- 变量名必须完全一致：-P foo:42 对应代码块中 foo = ...；大小写、下划线均需严格匹配。
- 默认值必须提供：即使你总通过命令行传参，也需赋予初始值（如 foo = None 或 foo = "default"），否则渲染可能因变量未定义而失败。
- 仅限顶层变量：嵌套赋值（如 config.foo = 5）或局部作用域（函数内定义）不会被识别为参数。
- 支持多种类型：Quarto 会自动尝试转换基础类型（42 → int, "hello" → str, true/false → bool, null → None）。
? 验证与调试建议
若参数未生效，可添加诊断代码快速排查：
#| tags: [parameters] debug_mode = False
import sys
print("Python version:", sys.version)
print("Available variables in globals():", [k for k in globals().keys() if not k.startswith('_')])
print("Value of 'foo':", repr(globals().get('foo', 'NOT FOUND')))✅ 总结
Quarto 的 Python 参数机制依赖显式声明 + 元数据标记，而非隐式注入。只要确保：
- 参数变量在带 #| tags: [parameters] 的代码块中定义；
- 变量名与 -P key:value 中的 key 完全一致；
- 提供合理默认值；
即可安全、可靠地实现命令行驱动的动态报告生成。
