README

自动生成静态文件和资源文件的唯一哈希版本，以实现高效且可靠的浏览器缓存。

概述

此插件自动为您网站根目录内的静态文件（如JS、CSS、字体等）以及用户上传的资源生成缓存破坏的哈希版本。

对于静态文件，它通过创建一个可以在每次部署时运行的scan命令来实现

./craft file-versioner/scan

可以在模板中通过一个v模板过滤器访问

<link
  rel="stylesheet"
  href="{{'/css/styles.min.js'|v }}"
  type="text/css"
  charset="utf-8"
/>

对于资源文件，当上传新文件时自动进行版本控制。

背景

在生产环境中提供文件时，通常需要配置您的Web服务器使用Cache-Control头部的浏览器缓存。这会指示用户的浏览器保存特定文件的本地版本，而不是联系服务器。这节省了网络请求并提高了性能。

当文件的内容发生变化时，浏览器缓存的常见问题是：浏览器如何知道它已更改？如果您告诉浏览器保留该文件2周，它将不会在那时再次请求该文件，这意味着它将继续使用旧的过时版本。

文件版本控制是解决这个问题的一种方法。其想法是在文件的末尾附加一个哈希值

这意味着当文件内容发生变化时，哈希值也会发生变化。当哈希值发生变化时，URL也会发生变化。这意味着用户的浏览器现在将始终获取最新的文件，但在此文件未更改时，仍将利用缓存。

版本控制挑战

实际上实施文件版本控制可能很困难。网站通常有两种文件类型

• 静态文件：这些是在开发期间使用的文件。想想看，它们是您的'构建时'文件
• 资源文件：这些是终端用户在常规使用期间上传的文件。想想看，它们是您的'运行时'文件

对于静态文件，您可以使用类似styles.v1.css styles.v2.css等的系统手动进行版本控制，但这既麻烦又容易出错。您还可以使用前端任务运行器（如gulp）来为您完成，但这也需要手动干预。

对于资源文件，选择更少。您可以要求客户在上传文件之前手动进行版本控制，但这不太可能得到遵守。

解决方案

解决方案是自动对静态文件和资源文件进行版本控制。此插件通过提供'构建时'CLI命令来实现这一点，这些命令可以在部署期间自动为静态文件进行版本控制，并在透明'运行时'处理中自动为所有用户上传的资源进行版本控制。

在关于文件版本控制的博客文章中了解更多信息

要求

此插件需要Craft CMS 3.0.0或更高版本。

安装

要安装插件

1. 打开您的终端并转到您的Craft项目

   $ cd /path/to/project

2. 然后告诉Composer加载插件

   $ composer require weareferal/file-versioner

3. 在控制面板中，转到设置→插件，然后点击File Versioner的安装按钮。

配置

将存储库中的示例配置文件config/file-versioner.example.php复制到您的项目中的config/file-versioner.php

<?php

return [
    '*' => [
        'staticVersioningEnabled' => false,
        'assetVersioningEnabled' => false,
    ],
    'production' => [
        // Whether or not to enable versioning for static files specifically.
        // Static files are the JS, CSS, png, jpeg, fonts ... that you use
        // part of your development workflow
        'staticVersioningEnabled' => true,

        // The extensions of the static files you are interested in being
        // hashed. In this example, we are only hashing JS & CSS files
        'staticVersioningExtensions' => 'css,js',

        // The name of the folder within your webroot to storge copied, versioned
        // files. This makes it easy to add this folder to your gitignore so that
        // generated version files are not in your repo.
        'staticVersioningPrefix' => 'versions',

        // Whether or not to enable versioning for uploaded Craft asset files.
        // This may or may not be something you need.
        'assetVersioningEnabled' => true,

        // The extensions of the asset files you are interested in being hashed.
        'assetVersioningExtensions' => 'png,jpg,jpeg,pdf'
    ]
];

此配置文件允许您根据环境分别控制版本控制。

例如，您还应将@webroot/versions文件夹添加到您的.gitignore

...
web/versions

使用

静态文件

要生成带版本的静态文件，请在部署过程中运行以下命令：

./craft file-versioner/scan

模板过滤器

要从模板中引用您的静态文件，请使用v Twig 过滤器

<script type="text/javascript" src="{{'/js/scripts.min.js'|v}}"></script>

这将透明地渲染您的带版本文件

<script
  type="text/javascript"
  src="/js/scripts.min.93477db0cd0ca27669fac6e6aac05c8b.js"
></script>

资产文件

对于通过控制面板上传的新文件，您不需要做任何事情——它们将自动生成版本。

幕后

在幕后，插件将所有带版本的文件保存在一个单独的@webroot/versions文件夹中。这意味着您的原始文件永远不会被更改。

静态文件

对于静态文件，scan命令将自动搜索您通过staticVersioningExtensions启用的扩展名的所有文件。

它将自动排除cpresources文件夹以及您webroot中的任何卷，以免重复生成带版本的文件或无谓地重命名其他内容。

它找到的文件将进行md5散列，并将该散列值追加到文件名中，在扩展名之前。

未带版本文件到带版本文件的映射保存在Craft缓存中。当您使用v模板过滤器时，插件只需在您的缓存中查找原始文件路径。

注意事项

在开发此插件时应注意以下几点。

CSS或JS中的版本

您不能在.twig文件之外访问带版本的文件。例如，您可能在CSS文件中有一个背景图片

.image {
  background-image: url("/images/background.png");
}

由于v模板过滤器在CSS文件中不可用，因此您不能访问带版本的文件。一种解决方案是使用内联样式，例如

<div
  class="image"
  style="background-image: url({{'/images/background.png'|v}})"
></div>

相对路径

在使用带版本的CSS或JS中的静态文件时，请小心使用相对路径，这可能会导致404错误。例如

@font-face {
  font-family: "Font";
  src: url("../fonts/Font.eot");
  src: url("../fonts/Font.eot?#iefix") format("embedded-opentype"), url("../fonts/Font.woff2")
      format("woff2"), url("../fonts/Font.woff") format("woff"), url("../fonts/Font.ttf")
      format("truetype");
  font-weight: normal;
  font-style: italic;
}

如上所述的注意事项中提到，您不能对此字体文件进行版本控制。但是，由于使用了相对路径，实际上会出现404错误。

这是因为所有带版本的资产都存储在webroot中的versions文件夹中。但此字体文件没有进行版本控制，因此不存在于versions文件夹中。

请使用绝对路径（到非版本化文件夹）

@font-face {
  font-family: "Font";
  src: url("/fonts/Font.eot");
  src: url("/fonts/Font.eot?#iefix") format("embedded-opentype"), url("/fonts/Font.woff2")
      format("woff2"), url("/fonts/Font.woff") format("woff"), url("/fonts/Font.ttf")
      format("truetype");
  font-weight: normal;
  font-style: italic;
}

本地卷文件

目前，此插件仅适用于您文件系统webroot中的本地文件。

SourceMaps

目前这些在启用版本控制的情况下无法正常工作。更多信息请查看

https://github.com/weareferal/craft-file-versioner/issues/3

支持

由Feral提供。如有任何问题，请通过timmy@weareferal.com发送电子邮件或在GitHub上提交问题。