解决 cargo-generate 模板中 GitHub Actions 与 Liquid 语法冲突问题

问题背景

在使用 cargo-generate 工具创建项目模板时，开发者经常需要在模板文件中同时处理两种不同的占位符语法：一种是 cargo-generate 使用的 Liquid 模板语法，另一种是 GitHub Actions 工作流文件中的表达式语法。这两种语法都使用类似的双大括号格式，导致在同一个文件中使用时会出现冲突。

冲突表现

具体表现为：

1. 当 GitHub Actions 工作流文件中包含 ${{ github.expression }} 这样的语法时
2. 同时文件中又包含 Liquid 模板语法如 {{ crate_name }}
3. cargo-generate 在处理时会无法正确识别 Liquid 占位符
4. 最终生成的模板中，Liquid 占位符没有被正确替换

技术原理分析

cargo-generate 使用 Liquid 作为模板引擎，其语法解析器会扫描文件中的 {{ }} 模式。当遇到 GitHub Actions 的表达式语法 ${{ }} 时，由于也符合 Liquid 的语法模式，会导致解析器混淆。

GitHub Actions 表达式语法通常包含以下特征：

• 以 ${{ 开头和 }} 结尾
• 内部可能包含点号、括号等特殊字符
• 常用于引用环境变量、步骤输出等

解决方案

经过社区探索，发现可以通过 Liquid 的过滤器功能来解决这个问题。具体方法是将 GitHub Actions 表达式转换为 Liquid 模板输出：

${{ "github.expression" | prepend: "{{ " | append: " }}" }}

这种方法的工作原理：

1. 将原本的 GitHub Actions 表达式作为字符串处理
2. 使用 prepend 过滤器在前面添加 {{
3. 使用 append 过滤器在后面添加 }}
4. 最终输出为 ${{ github.expression }}，既保持了 GitHub Actions 的语法，又避免了与 Liquid 解析器的冲突

自动化处理方案

对于包含大量 GitHub Actions 表达式的文件，可以编写脚本自动转换：

gsed -i 's/\${{\([^\}]\+\)\}\}/${{"\1" | prepend: "{{" | append: "}}"}}/g' .github/workflows/*.yaml

这个命令会：

1. 查找所有 ${{...}} 模式的字符串
2. 将其转换为 Liquid 过滤器形式
3. 直接修改原文件

实际应用示例

转换前的工作流文件片段：

env:
  VERSION: ${{ needs.get-version.outputs.version }}
steps:
  - uses: actions/checkout@v4
    with:
      repo_token: ${{ secrets.GITHUB_TOKEN }}

转换后的工作流文件片段：

env:
  VERSION: ${{ "needs.get-version.outputs.version" | prepend: "{{" | append: "}}" }}
steps:
  - uses: actions/checkout@v4
    with:
      repo_token: ${{ "secrets.GITHUB_TOKEN" | prepend: "{{ " | append: " }}" }}

最佳实践建议

1. 预处理工作流文件：在模板项目中预先转换好 GitHub Actions 工作流文件
2. 使用构建钩子：通过 cargo-generate 的 pre-hook 在生成时自动执行转换
3. 文档说明：在项目文档中明确说明这种转换的必要性和方法
4. 版本控制：保留原始工作流文件，方便后续更新维护

总结

通过这种巧妙的 Liquid 过滤器应用，我们成功解决了 cargo-generate 模板中两种模板语法冲突的问题。这种方法既保持了 GitHub Actions 工作流的原有功能，又确保了 cargo-generate 能够正确解析 Liquid 模板占位符，为创建复杂的项目模板提供了可靠的技术方案。