README

增强Kirby的css()和js()助手以支持哈希文件名。传递您的正常路径（例如…main.js）——该插件将查找哈希资产并将路径自动转换（例如…main.20201226.js）。这样，您甚至可以在开发和生产环境中保持资产路径相同！

主要功能

• 🛷 无需查询字符串即可缓存破坏资产
• 🎢 无需web服务器重写规则！
• ⛸ 支持manifest.json
• 🎿 支持手动哈希文件名
• ☃️ 使用hashedUrl()助手创建预加载链接

使用哈希资产插件的项目

• plainkit-hashed-assets – 基于 Kirby plain kit 的简单演示
• realtroll.de – 使用此插件进行资产哈希的干净网站

要求

• PHP 8.0+
• Kirby 3.7+

安装

下载

下载并将此存储库复制到/site/plugins/kirby-hashed-assets。

Git子模块

git submodule add https://github.com/johannschopplich/kirby-hashed-assets.git site/plugins/kirby-hashed-assets

Composer

composer require johannschopplich/kirby-hashed-assets

用法

使用manifest.json进行自动哈希

为此插件，此插件使用hashup npm包进行文件哈希。

hashup是一个小巧的CLI工具，有两个目标是为了您的新构建资产

1. 重命名或更确切地说，哈希（因此得名）资产。
2. 为他们生成一个manifest.json。

您甚至不需要将其安装到devDependencies中，因为npx将一次性动态获取它。通过将hashup添加到您的package.json脚本（推荐）中，将hashup添加到构建管道中，例如

{
  "scripts": {
    "clean": "rm -rf public/assets/{css,js}",
    "build": "npm run clean && <...> && npx -y hashup"
  }
}

现在，像通常那样传递资产路径到Kirby的资产助手

<?= js('assets/js/main.js') ?>
// `<script src="https://example.com/assets/js/main.9ad649fd.js"></script>

如果manifest.json中找到相应的哈希文件，它将被使用并渲染。

对于特定于模板的资产，使用@template（而不是@auto）

<?= js('@template') ?>
// `<script src="https://example.com/assets/js/templates/home.92c6b511.js"></script>`

警告

如果没有模板文件存在，则将回显https://example.com/@template。这将导致HTTP错误和内容被阻止，因为请求的文件不存在，并且将返回错误页面的HTML。

如果您不确定模板文件是否存在，请使用以下助手

• cssTpl()
• jsTpl()

它们将仅在当前页面的模板存在时回显链接标签和脚本标签。

手动哈希

对于较小的网站，您可能更喜欢没有构建链，但仍然想利用某种形式的资产哈希。在这种情况下，您可以手动重命名您的文件。

以一个虚构的main.js为例。只需像通常一样在您的片段之一中包含它

<?= js('assets/js/main.js') ?>

现在以main.{hash}.js的格式重命名文件。您可以使用当前日期，例如：main.20201226.js，这将输出

<script src="https://example.com/assets/js/main.20201226.js"></script>

Voilà，无需更改资产路径，哈希文件将在模板中找到并渲染！

预加载链接的哈希文件名

您可以使用全局的 hashedUrl() 辅助函数来查找文件，就像您通常使用 css() 或 js() 辅助函数一样。虽然后两者返回一个链接或相应的脚本标签，但 hashedUrl() 辅助函数只会返回一个 URL，您可以在任何上下文中使用它。

<link rel="preload" href="<?= hashedUrl('assets/css/templates/default.css') ?>" as="style">
// <link rel="preload" href="/assets/css/templates/default.1732900e.css" as="style">

由于所有长期支持（evergreen）浏览器最终都原生支持 JavaScript 模块，您可能更喜欢预加载模块。

<link rel="modulepreload" href="<?= hashedUrl('assets/js/templates/home.js') ?>">
// <link rel="preload" href="/assets/js/templates/home.92c6b511.js">

许可证

MIT 许可证 © 2021-至今 Johann Schopplich