README

此插件是一个Twig扩展，可以帮助您清除静态资源（如CSS、JS、图片、视频或PDF）的缓存。它将版本号追加到资源URL，基于构建号或文件的最后修改时间。这确保了您的用户始终接收最新版本的文件，而无需清除浏览器缓存。

目录

1. 功能
2. 安装
3. 使用
4. 高级使用
   • 从字符串进行版本化
   • 从时间戳进行版本化
   • 从自定义文本文件进行版本化
   • 与PDF生成器或Varnish缓存进行版本化
   • 关于路径的说明
5. 许可协议
6. 致谢

功能

• 兼容Craft CMS 3.x、4.x和5.0.0.alpha
• 支持多种文件类型和缓存策略
• 允许从字符串或文本文件进行自定义版本化
• 与PDF生成器和Varnish缓存插件集成

安装

您可以从Craft插件商店或使用Composer安装此插件。

从插件商店

转到Craft控制面板中的插件商店部分，搜索“Static Files Autoversioning”。然后在它的模态窗口中点击“安装”按钮。

项目设置

要安装插件，请在终端导航到您的Craft项目

# go to the project directory
cd /path/to/my-project

# tell Composer to load the plugin
composer require cooltronicpl/craft-files-autoversioning

# tell Craft to install the plugin
./craft install/plugin craft3-files-autoversioning

使用

要使用此插件，您需要在模板中调用version()函数，并将资源路径作为参数传递。例如

<link rel="stylesheet" href="{{ version('/css/styles.css') }}">

这将输出类似以下内容

<link rel="stylesheet" href="/css/styles.css?v=12345678" />

版本号（v=12345678）是通过读取位于根项目文件夹中的名为build.txt的文件来确定的（与config、templates等文件并列）。您可以使用您的部署脚本来创建和更新此文件。例如，如果您使用CodeShip，可以使用以下命令

echo -n "${CI_BUILD_NUMBER}" > build.txt

高级使用

从字符串进行版本化

如果您想使用自定义字符串作为版本号，可以使用versionString()函数，将资源路径和字符串作为参数传递。例如

<link rel="stylesheet" href="{{ versionString('/css/styles.css', 'customstring') }}">

这将输出类似以下内容

<link rel="stylesheet" href="/css/styles.css?v=customstring">

从时间戳进行版本化

如果您想使用文件的最后修改时间作为版本号，无论是否存在build.txt文件，都可以使用versionTimestamp()函数，将资源路径作为参数传递。例如

<link rel="stylesheet" href="{{ versionTimestamp('/css/styles.css') }}">

这将输出类似以下内容

<link rel="stylesheet" href="/css/styles.css?v=1667385206">

从自定义文本文件进行版本化

如果您想使用自定义文本文件的内容作为版本号，可以使用versionCustom()函数，将资源路径和文本文件名作为参数传递。文本文件应位于您的根项目文件夹中。例如

<link rel="stylesheet" href="{{ versionCustom('/css/styles.css', 'mods.txt') }}">

这将输出类似以下内容

<link rel="stylesheet" href="/css/styles.css?v=modded">

假设mods.txt文件包含单词“modded”。

与PDF生成器或Varnish缓存进行版本化

您还可以在您的托管或服务器缓存PDF文件时与此插件一起使用PDF生成器。或者，您的文件由缓存插件（如Varnish Cache）缓存。

<a href="{{alias('@web')}}{{version("/" ~ craft.documentHelper.pdf('_pdf/document.twig', 'file', 'pdf/book'  ~ '.pdf'  ,entry, pdfOptions))}}">LINK</a>

这将输出类似以下内容

<a href="http://some-domain.com/pdf/book.pdf?v=1668157143">LINK</a>

这会生成一个带版本号的PDF，解决您托管中的任何缓存策略问题。

关于路径的说明

默认情况下，插件在@webroot目录中搜索要版本化的文件，并在@root路径中搜索build.txt或自定义文本文件。

注意：您可以在Craft CMS文档中了解更多关于@webroot和@root别名及其配置信息。

许可协议

本插件遵循 GPLv3 许可协议授权。

致谢

本插件由 CoolTRONIC.pl sp. z o.o. (LLC) 互动机构 和 Pawel Potacki 爱心奉献。