Quarto 支持通过 -P 参数从命令行传入变量，但需在文档中显式声明参数接收逻辑（如 #| tags: [parameters]），否则 Python 内核无法识别该变量，导致 NameError。本文详解正确用法及关键注意事项。
quarto 支持通过 `-p` 参数从命令行传入变量，但需在文档中显式声明参数接收逻辑（如 `#| tags: [parameters]`），否则 python 内核无法识别该变量，导致 `nameerror`。本文详解正确用法及关键注意事项。
在 Quarto 中为 Python 渲染流程注入动态参数，是实现可复用报告（如不同数据集、配置或版本）的关键能力。但与 R 环境不同，Python 并不会自动将 quarto render -P foo:5 中的 foo 注入全局命名空间——必须通过 参数单元格（parameter cell） 显式声明并初始化，默认值可选。
✅ 正确写法：声明参数单元格
在 .qmd 文件中，需添加一个带 #| tags: [parameters] 元数据的 Python 代码块，并为参数赋默认值（类型建议与预期一致）：
--- 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}")
# 输出示例：Received parameter 'foo' = 5（若未指定）或 123（若运行 quarto render test.qmd -P foo:123）
⚠️ 注意事项：
- #| tags: [parameters] 必须写在代码块首行，且不能有空行隔开；
- 参数名（如 foo）必须与命令行 -P foo:value 中的键名完全一致（区分大小写）；
- 值类型由 Python 解析：-P foo:42 → int；-P foo:"hello" → str；-P foo:true → bool；支持 JSON 格式如 -P config:'{"host":"localhost","port":8080}'；
- 若未提供命令行参数，将使用代码块中定义的默认值；
- 不要尝试访问 params.foo 或 quarto.params.foo —— 这是 R 的语法，在 Python 中无效。
? 验证与调试建议
运行以下命令测试参数传递是否生效：
quarto render test.qmd -P foo:99 --output test_out.html
渲染后打开 test_out.html，应看到输出：Received parameter 'foo' = 99。
若仍报 NameError: name 'foo' is not defined，请检查：
- 参数单元格是否遗漏 #| tags: [parameters]；
- 是否误将该标记写在注释行（# 后需紧跟 |，且无空格）；
- 是否在参数单元格之后才首次引用 foo（顺序不可逆）；
- Quarto 版本是否 ≥ 1.4（参数功能在早期版本中不完善，推荐升级至最新稳定版）。
掌握这一模式后，你可轻松构建参数化报告流水线，例如结合 CI/CD 动态生成测试摘要、按环境切换 API 端点，或批量渲染多组实验结果——所有逻辑均封装于单一 .qmd 文件中，简洁而健壮。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
