在 Quarto 中通过命令行传递参数（如 -P foo:5）后，需在文档中显式声明参数变量并添加 #| tags: [parameters] 元数据，Python 才能识别并注入该值；直接使用 foo 会导致 NameError。
在 quarto 中通过命令行传递参数（如 `-p foo:5`）后，需在文档中显式声明参数变量并添加 `#| tags: [parameters]` 元数据，python 才能识别并注入该值；直接使用 `foo` 会导致 `nameerror`。
Quarto 支持跨语言的参数化渲染，但在 Python 引擎中，参数不会自动注入全局命名空间——与 R 中的 params$foo 不同，Python 要求你主动声明参数变量并标记为参数单元格。这是关键区别，也是初学者常踩的坑。
✅ 正确做法：两步声明参数
- 定义带默认值的变量，并在代码块开头添加 #| tags: [parameters] 元数据（必须在同一代码块内）；
- 后续任意 Python 代码块中即可直接使用该变量。
示例 test.qmd（精简优化版）：
---
title: "Test File"
format: html
html:
embed-resources: true
execute:
echo: false
jupyter: python3
---
# Title
Print this in report
```{python}
#| tags: [parameters]
foo = 5 # 默认值，将被命令行 -P foo:123 覆盖# 使用参数（无需 params. 前缀）
print(f"Received parameter 'foo' = {foo}")
print(f"Type: {type(foo)}") # 自动转换为对应类型（如数字、字符串、布尔值）执行命令（覆盖默认值）： ```bash quarto render test.qmd -P foo:42 --output test_cmd_out.html
输出 HTML 中将显示：
Received parameter 'foo' = 42
Type: <class 'int'>
⚠️ 注意事项
- #| tags: [parameters] 必须写在定义变量的同一代码块中，且变量名需与 -P key:value 中的 key 完全一致（区分大小写）；
- Quarto 会自动将命令行传入的值转换为合理 Python 类型：42 → int，"hello" → str，true/false → bool；若需强制字符串，请用引号：-P foo:"123"；
- 不支持在单个代码块中混合参数声明与业务逻辑（如 #| tags: [parameters] + print(foo)），应严格分离；
- 若未传参且无默认值（如仅写 foo = None），运行时将报错，因此建议始终提供安全默认值。
? 验证与调试技巧
可在文档末尾添加诊断块快速检查参数状态：
立即学习“Python免费学习笔记（深入）”；
#| echo: true
# Debug: list all parameter variables
import inspect
frame = inspect.currentframe().f_back
params_vars = {k: v for k, v in frame.f_locals.items()
if not k.startswith('_') and not callable(v)}
print("Available parameters:", params_vars)掌握这一机制后，你就能灵活构建可复用的报告模板——例如批量生成不同用户/日期/阈值的分析结果，全部通过 quarto render 命令驱动，无需修改 .qmd 源码。
