跳转到导航 跳转到主要内容
头条
W3C技术联盟，2024 年回顾
CNB版本
社区版
cnb.cool
国外版
cnb.build
2025/12/14

Liquid

模板语言：
本页大纲
Eleventy 简称 文件扩展名 npm 包
liquid .liquid liquidjs
Eleventy 版本 liquidjs 版本
@11ty/eleventy@0.x liquidjs@6.x
@11ty/eleventy@1.x liquidjs@9.x
@11ty/eleventy@2.x liquidjs@10.x
@11ty/eleventy@3.x liquidjs@10.x

您可以覆盖 .liquid 文件的模板引擎。阅读更多关于更改模板的渲染引擎的内容。

Liquid 选项

默认选项

为了避免不断修复过时的文档，请在 Liquid.js 中查找 getLiquidOptions。这些选项与默认的 liquidjs 选项不同。

Liquid 中的 JavaScript 真值判断

对 JavaScript 开发者来说可能很意外——在 LiquidJS 中 "" 和 0 都是真值！如果您想切换使用更符合 JavaScript 约定的方式，请在 Eleventy 配置中使用 Liquid 选项 jsTruthy: true：

eleventy.config.js
export default function (eleventyConfig) {
eleventyConfig.setLiquidOptions({
jsTruthy: true,
});
};
module.exports = function (eleventyConfig) {
eleventyConfig.setLiquidOptions({
jsTruthy: true,
});
};

使用您自己的选项

建议使用配置 API 来覆盖上面的默认选项。

eleventy.config.js
export default function (eleventyConfig) {
eleventyConfig.setLiquidOptions({
dynamicPartials: false,
strictFilters: false, // 在 Eleventy 1.0 中从 `strict_filters` 重命名
});
};
module.exports = function (eleventyConfig) {
eleventyConfig.setLiquidOptions({
dynamicPartials: false,
strictFilters: false, // 在 Eleventy 1.0 中从 `strict_filters` 重命名
});
};

可选：设置您自己的库实例

作为高级使用的替代机制，使用配置 API 传入您自己的 Liquid 库实例。查看所有 liquidjs 选项。

WARNING
与上面的 `setLiquidOptions` 不兼容——此方法将**覆盖**在那里设置的任何配置。
eleventy.config.js
import { Liquid } from "liquidjs";

export default function (eleventyConfig) {
let options = {
extname: ".liquid",
dynamicPartials: false,
strictFilters: false, // 在 Eleventy 1.0 中从 `strict_filters` 重命名
root: ["_includes"],
};

    eleventyConfig.setLibrary("liquid", new Liquid(options));

};
const { Liquid } = require("liquidjs");

module.exports = function (eleventyConfig) {
let options = {
extname: ".liquid",
dynamicPartials: false,
strictFilters: false, // 在 Eleventy 1.0 中从 `strict_filters` 重命名
root: ["_includes"],
};

    eleventyConfig.setLibrary("liquid", new Liquid(options));

};

支持的功能

功能 语法
✅ 包含 {% include user %} 查找 _includes/user.liquid。不处理 include 文件中的前置内容。
✅ 包含（相对路径） 相对路径使用 ./（模板的目录）或 ../（模板的父目录）：{% include ./included %} 在模板的当前目录中查找 included.liquid。不处理前置内容。

WARNING
如果 _includes/included.liquid 也存在，Liquid 将使用这个文件。
✅ 包含（带引号）
从 Eleventy 1.0 开始，不带引号的 Liquid 包含需要 dynamicPartials: false——阅读更多关于带引号的包含路径的内容。
{% include 'user' %} 查找 _includes/user.liquid。不处理 include 文件中的前置内容。
✅ 包含（相对路径，带引号）
从 Eleventy 1.0 开始，不带引号的 Liquid 包含需要 dynamicPartials: false——阅读更多关于带引号的包含路径的内容。
相对路径使用 ./（模板的目录）或 ../（模板的父目录）：{% include './dir/user' %} 从模板的当前目录查找 ./dir/user.liquid。不处理 include 文件中的前置内容。

WARNING
如果 _includes/dir/user.liquid 也存在，Liquid 将使用这个文件。
✅ 包含（传入数据） {% include 'user' with 'Ava' %}。不处理 include 文件中的前置内容。
✅ 包含（传入数据） {% include 'user', user1: 'Ava', user2: 'Bill' %}。不处理 include 文件中的前置内容。
✅ 自定义过滤器 {{ name | upper }} 阅读更多关于过滤器的内容
✅ 通用过滤器 {% name | filterName %} 阅读更多关于过滤器的内容
✅ 自定义标签 {% uppercase name %} 阅读更多关于自定义标签的内容。
✅ 短代码 {% uppercase name %} 阅读更多关于短代码的内容。

带引号的包含路径

如果您使用 Liquid 模板，这是一个常见的陷阱。

如果您想使用不带引号的包含路径，必须在 Liquid 选项中启用 dynamicPartials: false。Eleventy 1.0（和 liquidjs）中的默认值从 false 更改为 true。在问题 #72阅读更多关于这个限制的内容。

默认行为，dynamicPartials: true

{% include 'user' %} 查找 _includes/user.liquid

使用 dynamicPartials: false 的不带引号包含

{% include user %} 查找 _includes/user.liquid

过滤器

过滤器用于转换或修改内容。您可以添加 Liquid 特定的过滤器，但您可能想添加通用过滤器。

阅读更多关于LiquidJS 过滤器语法的内容。

请注意，Liquid 原生支持异步过滤器（不需要任何额外的代码或 API 方法更改）。

eleventy.config.js
export default function(eleventyConfig) {
// Liquid 过滤器
eleventyConfig.addLiquidFilter("myLiquidFilter", function(myVariable) { /_ … _/ });

// 也支持异步
eleventyConfig.addLiquidFilter("myAsyncLiquidFilter", async function(myVariable) { /_ … _/ });

// 通用过滤器（添加到 Liquid、Nunjucks、11ty.js）
eleventyConfig.addFilter("myFilter", function(myVariable) { /_ … _/ });
};
module.exports = function(eleventyConfig) {
// Liquid 过滤器
eleventyConfig.addLiquidFilter("myLiquidFilter", function(myVariable) { /_ … _/ });

// 也支持异步
eleventyConfig.addLiquidFilter("myAsyncLiquidFilter", async function(myVariable) { /_ … _/ });

// 通用过滤器（添加到 Liquid、Nunjucks、11ty.js）
eleventyConfig.addFilter("myFilter", function(myVariable) { /_ … _/ });
};

使用方法

<h1>{{ myVariable | myFilter }}</h1>

多个过滤器参数

eleventy.config.js
export default function (eleventyConfig) {
// Liquid 过滤器
eleventyConfig.addLiquidFilter(
"concatThreeStrings",
function (arg1, arg2, arg3) {
return arg1 + arg2 + arg3;
}
);
};
module.exports = function (eleventyConfig) {
// Liquid 过滤器
eleventyConfig.addLiquidFilter(
"concatThreeStrings",
function (arg1, arg2, arg3) {
return arg1 + arg2 + arg3;
}
);
};
 
<h1>{{ "first" | concatThreeThings: "second", "third" }}</h1>

短代码

短代码基本上是可重用的内容片段。您可以添加 Liquid 特定的短代码，但您可能想添加通用短代码。

短代码

eleventy.config.js
export default function(eleventyConfig) {
// Liquid 短代码
// 这些也可以是异步函数
eleventyConfig.addLiquidShortcode("user", function(name, twitterUsername) { /_ … _/ });

// 通用短代码（添加到 Liquid、Nunjucks、11ty.js）
eleventyConfig.addShortcode("user", function(name, twitterUsername) {
return `<div class="user">

<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`;
  });
};
module.exports = function(eleventyConfig) {
// Liquid 短代码
// 这些也可以是异步函数
eleventyConfig.addLiquidShortcode("user", function(name, twitterUsername) { /_ … _/ });

// 通用短代码（添加到 Liquid、Nunjucks、11ty.js）
eleventyConfig.addShortcode("user", function(name, twitterUsername) {
return `<div class="user">

<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`;
  });
};

liquidjs 在内部已经基于 Promise，所以短代码函数的 async function 在这里可以直接使用。

使用方法

{% user "Zach Leatherman", "zachleat" %}

<!-- 在 Liquid 模板中参数之间的逗号是可选的 -->
{% user "Zach Leatherman" "zachleat" %}
输出
<div class="user">
	<div class="user_name">Zach Leatherman</div>
	<div class="user_twitter">@zachleat</div>
</div>

成对短代码

eleventy.config.js
export default function(eleventyConfig) {
// Liquid 短代码
// 这些也可以是异步函数
eleventyConfig.addPairedLiquidShortcode("user2", function(bioContent, name, twitterUsername) { /_ … _/ });

// 通用短代码（添加到 Liquid、Nunjucks、11ty.js）
eleventyConfig.addPairedShortcode("user2", function(bioContent, name, twitterUsername) {
return `<div class="user">

<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`;
  });
};
module.exports = function(eleventyConfig) {
// Liquid 短代码
// 这些也可以是异步函数
eleventyConfig.addPairedLiquidShortcode("user2", function(bioContent, name, twitterUsername) { /_ … _/ });

// 通用短代码（添加到 Liquid、Nunjucks、11ty.js）
eleventyConfig.addPairedShortcode("user2", function(bioContent, name, twitterUsername) {
return `<div class="user">

<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`;
  });
};

liquidjs 在内部已经基于 Promise，所以短代码函数的 async function 在这里可以直接使用。

使用方法

请注意，您可以在 {% user %} 短代码内放置任何 Liquid 标签或内容！是的，甚至其他短代码也可以！

{% user2 "Zach Leatherman" "zachleat" %} Zach likes to take long walks on
Nebraska beaches. {% enduser2 %}
输出
<div class="user">
	<div class="user_name">Zach Leatherman</div>
	<div class="user_twitter">@zachleat</div>
	<div class="user_bio">Zach likes to take long walks on Nebraska beaches.</div>
</div>

异步短代码

Liquid 在内部已经基于 Promise，所以带有 await 的 async 函数可以直接使用。

eleventy.config.js
export default function (eleventyConfig) {
eleventyConfig.addLiquidShortcode(
"user",
async function (name, twitterUsername) {
return await fetchAThing();
}
);

    eleventyConfig.addPairedShortcode(
    	"user2",
    	async function (content, name, twitterUsername) {
    		return await fetchAThing();
    	}
    );

};
module.exports = function (eleventyConfig) {
eleventyConfig.addLiquidShortcode(
"user",
async function (name, twitterUsername) {
return await fetchAThing();
}
);

    eleventyConfig.addPairedShortcode(
    	"user2",
    	async function (content, name, twitterUsername) {
    		return await fetchAThing();
    	}
    );

};

使用方法

（使用方法相同。）

{% user "Zach Leatherman" "zachleat" %} {% user2 "Zach Leatherman" "zachleat" %}
Zach likes to take long walks on Nebraska beaches. {% enduser2 %}

短代码参数解析

Eleventy 包含自己的短代码参数解析实现。要切换到更健壮的、Liquid 原生的解决方案，请使用 setLiquidParameterParsing 配置 API 方法。这可能会在 Eleventy 的未来主要版本中默认启用。相关GitHub #2679。

eleventy.config.js
export default function (eleventyConfig) {
// 当前默认：
// eleventyConfig.setLiquidParameterParsing("legacy");

    // Liquid 原生
    eleventyConfig.setLiquidParameterParsing("builtin");

};
module.exports = function (eleventyConfig) {
// 当前默认：
// eleventyConfig.setLiquidParameterParsing("legacy");

    // Liquid 原生
    eleventyConfig.setLiquidParameterParsing("builtin");

};

访问 page 数据值

如果您不使用箭头函数，Liquid 短代码（以及 Nunjucks 和 11ty.js JavaScript 函数）将可以访问 Eleventy page 数据值，而无需将它们作为参数传入。

eleventy.config.js
export default function (eleventyConfig) {
eleventyConfig.addLiquidShortcode("myShortcode", function () {
// 在 0.11.0 及更高版本中可用
console.log(this.page);

    	// 例如：
    	console.log(this.page.url);
    	console.log(this.page.inputPath);
    	console.log(this.page.fileSlug);
    });

};
module.exports = function (eleventyConfig) {
eleventyConfig.addLiquidShortcode("myShortcode", function () {
// 在 0.11.0 及更高版本中可用
console.log(this.page);

    	// 例如：
    	console.log(this.page.url);
    	console.log(this.page.inputPath);
    	console.log(this.page.fileSlug);
    });

};

其他页面在 Template Languages