@4awpawz/buster 中文文档教程
A Cache Buster Called Buster
Buster 解决您的浏览器缓存问题!
Version
1.0.0
Features
缓存将您的项目文件就地破坏。
使用基于 MD5 哈希的缓存清除文件名对文件进行指纹识别(重命名)。
将文件中对原始文件名的引用替换为其基于 MD5 散列的文件名。
可选择将清单文件输出到 buster.manifest.json。
使用 .buster.json 进行简单直观的配置。
可通过命令行调用和编写脚本。
轻松集成到您的项目工作流程中。
Installation
Install Globally
$ npm install -g @4awpawz/buster
Install Locally
$ npm install --save-dev @4awpawz/buster
Buster Primer
Project Relative File Paths And Site Relative URLs
在随后的文档中,引用了项目相对文件路径 和站点相对 URL。
“项目相对文件路径”严格适用于项目的文件结构。 它们用于声明操作指令中的输入,当声明项目中资产的文件路径时,您希望 Buster 将其作为缓存目标破坏。
“站点相对 URL”严格属于您网站的运行时环境,用于引用整个站点的资产(例如 img 标签的 src 属性,href 属性链接标记,在 CSS 样式表中声明的 URL() CSS 函数)。
这里重要的是要了解,为了让 Buster 执行缓存清除,您(开发人员)必须确保您的站点在引用其资产时使用站点相对 URL。 这是因为 Buster 将您的项目相对文件路径转换为站点相对 URL,然后它会使用这些 URL 来搜索您站点文件的内容以查找需要更新以指向其具有唯一哈希指纹的资产的站点相对 URL。
A Typical Buster Work Flow
您的开发构建工具会将您的生产就绪站点(与开发相对)生成到您项目的发布文件夹中。 在配置 Buster 以缓存您的站点时,您可以通过在 Buster 配置的 操作指令。 然后从项目的根目录中,您可以使用命令行运行 Buster 以在发布文件夹中缓存 bust 您的站点。 然后您可以从发布文件夹运行您的网站以确保它按预期运行,一旦确定它按预期运行,您就可以使用命令行实用程序将您的网站直接从发布文件夹部署到其服务器,例如同步。
在具有以下或类似项目结构
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.jpg
|- |- |- index.html
|- |- .buster.json
的典型网站项目中,用于目标 housecat.jpg 的操作指令中的项目相对文件路径将是 release/media/housecat.jpg 以及用于在浏览器中识别图像文件的站点相对 URL将是 media/housecat.jpg。
Operational Directives
Buster 采用了一个称为操作指令 的概念,缩写为 od,您可以在.buster.json 配置中声明文件以及 Buster 使用哪个来指导它对项目文件执行的操作。 每个 od 由两部分组成,输入 和操作。
Input
一个或多个文件的项目相对文件路径。
支持 globs/wildcard 模式。
重要 Buster 假定所有项目相关文件路径都与
process.cwd()
相关。重要 Buster 使用节点包glob 实现其glob 支持。 如果您需要有关将 globs 与 Buster 结合使用的更多信息,请参阅节点包 glob。
Operation
指示 Buster 将对 od 的输入文件执行的操作。 它是一个数字,前面有一个冒号,将数字与输入分开(例如“:1”)。 目前支持以下 3 种操作:
:1
仅将此操作应用于其文件名要被指纹识别以用于缓存清除目的的那些文件(例如 .jpg、.gif、.map
)。
每个基于 MD5 哈希的唯一文件名的格式将是[原始文件的基本名称].[唯一哈希].[原始文件的扩展名](例如 cat.[unique hash].jpg )。 如果原始文件的基本名称包含 1 个或多个句点(例如main.js.map),例如,基于 MD5 哈希的文件名的格式将是main.[唯一哈希].js.map。
:2
仅将此操作应用于那些要搜索其内容以查找指向资产的站点相关 URL 的文件,这些 URL 的文件名已被指纹识别,因此需要更新,并且其自身的文件名不会被指纹识别以用于缓存破坏目的。
:3
仅将此操作应用于那些为了缓存清除目的而对其文件名进行指纹识别的文件(例如 .jpg、.gif、.map
)以及要搜索其内容以查找指向的站点相关 URL 的文件文件名已被指纹识别并因此需要更新的资产。
每个基于 MD5 哈希的唯一文件名的格式将是[原始文件的基本名称].[唯一哈希].[原始文件的扩展名](例如 cat.[unique hash].jpg )。 如果原始文件的基本名称包含 1 个或多个句点(例如main.js.map),例如,基于 MD5 哈希的文件名的格式将是main.[唯一哈希].js.map。
Operational Directive Examples
Example Operational Directives Using Project Relative File Path:
给定以下项目结构
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.jpg
|- |- |- index.html => contains img tag with a site relative url for its src i.e. <img src="/media/housecat.jpg">
|- |- .buster.json
并使用以下操作指令从 myproject 文件夹中的命令行运行 Buster
`release/media/housecat.jpg:1`
`release/index.html:2`
将产生以下结果:
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.[unique hash].jpg
|- |- |- index.html => now contains img tag whose src attribute points to hashed img i.e. <img src="/media/housecat.[unique hash].jpg">
|- |- .buster.json
Example Operational Directives Using Project Relative File Paths And Globs:
给定以下项目结构
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.jpg
|- |- |- |- purringcat.jpg
|- |- |- |- bigcats/
|- |- |- |- |- lion.jpg
|- |- |- |- |- tiger.jpg
|- |- |- index.html => contains img tags with site relative urls for its src e.g. <img src="/media/housecat.jpg">, <img src="/media/bigcats/lion.jpg">
|- |- .buster.json
并使用以下指令运行 Buster
`release/media/**/*.jpg:1
`release/**/*.html:2`
将产生如下结果:
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.[unique hash].jpg
|- |- |- |- purringcat.[unique hash].jpg
|- |- |- |- bigcats/
|- |- |- |- |- lion.[unique hash].jpg
|- |- |- |- |- tiger.[unique hash].jpg
|- |- |- index.html => now contains img tags whose src attributes point to hashed img i.e. <img src="/media/housecat.[unique hash].jpg">, <img src="/media/bigcats/lion.[unique hash].jpg">
|- |- .buster.json
buster.json Configuration
重要 Buster 希望 .buster.json 与 package.json 一起驻留在项目的根文件夹中。
{
"options": {
"manifest": true,
"verbose": true,
"ignore": "media/original/**/*.jpg,media/original/**/*.gif"
},
"directives": [
"release/media/**/*.jpg:1",
"release/./index.html:2",
"release/css/test.css:3",
"release/script/test.js:3"
]
}
Options
Buster 支持以下配置选项:
ignore
一个或多个逗号分隔的项目相对文件路径到要忽略的文件的引号列表,默认为""< /代码>。
支持 globs 和 wildcard 字符模式。
manifest
布尔值,true
将清单保存到项目根文件夹 中的buster.manifest.json,默认为<代码>错误。
verbose
boolean,true
输出详细日志记录,默认为 false
。
Typical Workflows
Using Buster In Node Projects
在 Node 项目中使用 Buster 时,在本地安装 Buster:
~/Development/myproject > $ npm install --save-dev @4awpawz/buster
然后在项目的根文件夹中创建 .buster.json 以及 package.json。
{
"directives": [
"release/media/**/*.jpg:1",
"release/css/**/*.css.map:1",
"release/scripts/**/*.js.map:1",
"release/**/*.html:2",
"release/css/**/*.css:3",
"release/scripts/**/*.js:3"
]
}
然后创建一个 NPM 脚本来调用 buster 来缓存你的网站:
"scripts": {
"bust": "buster"
}
从你的项目的根文件夹,输入以下内容来缓存你的项目:
~/Development/myproject $ npm run bust
Calling Buster From A Script
Buster 可以从一个脚本调用,允许它是用作更大工作流程的一部分。
编写 Buster 脚本以缓存 bust 您的项目:
const buster = require("@4awpawz/buster");
const paramsConfig = {
options: {
manifest: true
},
directives: [
"release/media/**/*.jpg:1",
"release/css/**/*.css.map:1",
"release/scripts/**/*.js.map:1",
"release/**/*.html:2",
"release/css/**/*.css:3",
"release/scripts/**/*.js:3"
]
}
await buster(paramsConfig);
Filing Bugs And Feature Requests
- https://github.com/4awpawz/buster/issues
Changelog
v1.0.0
这是 Buster 的第一个主要版本,并包含许多与先前版本相比的重大更改。 最值得注意的是,之前的版本有一个“安全模式”配置选项,可以指示 Buster“就地”缓存 bust,这意味着它不会创建备份,也无法将文件恢复到之前的状态。 事实证明,绝大多数 Buster 用户都在使用“安全模式”,因为它符合他们将网站生成到专用文件夹的工作流程,该文件夹可以被缓存破坏,并且可以通过重新生成网站轻松地重新填充。 实施这些更改是为了重构 Buster 以精确匹配这种典型的工作流程。 您可以在 https:/ 阅读更多关于重构 Buster 的决定/gettriossg.com/blog/news/2021/03/23/next-feature-release/。
v0.3.1
此版本修复了仅由 Buster 内部使用的包的安全警告。 代码库没有变化。
v0.3.0
此版本解决了一个错误,并修复了仅供 Buster 内部使用的软件包的安全警告。 此版本的登陆还减少了控制台输出; 如果需要,使用 verbose
配置选项。
主要错误修复:
- Addresses issue
#14
which could cause Buster to mangle hashed file names. Please note that beginning with this release, Buster now generates hashed file names as [hash]-[file name].[file extension]. You are strongly advised to upgrade your projects and rebuild them.
v0.2.4
此版本解决了仅由 Buster 内部使用的包的安全警告修复。 代码库没有变化。
v0.2.3
主要错误修复:
v0.2.2
此版本不包含对代码库的更改。
- Addresses issue
#11
which seeks to lockdown all project dependencies including descendants using NPM'sshrinkwrap
.
v0.2.1
主要和次要错误修复 - 包括但不限于以下内容:
解决问题
10
这会导致 buster 在读取属于使用 paramsConfig 启动它的应用程序的命令行配置数据时失败。解决问题
#9
有时会导致恢复
到失败。 此修复程序完全取代了 v0.2.0 中引入的修复程序,现在可以在还原处理周期的早期处理该问题。
v0.2.0
主要重构 - 包括但不限于以下内容:
引入实验性 "safe mode" 功能,解决
#6
。v0.1.6 中断了备份文件错误的处理,修复了
#5
。在还原期间从 glob 返回的清单中删除散列文件。
实现目标路径的新解析。
从项目中删除“file-exists”包。
捕获一些异步异常以防止未解决的承诺异常。
配置首先尝试从 paramsConfig(即通过脚本传递)解析。
更新的 README.md 解决
v0.1.6
了命令行处理中的一个错误,当用户从命令行仅输入 “bust” 或 “restore” 时,该错误会导致 Buster 崩溃。
解决了 od 处理中的一个错误,该错误会导致 Buster 在尝试创建已存在的文件夹时崩溃。
解决了 od 处理中的一个错误,该错误会导致 Buster 在尝试删除不再存在的文件时崩溃。
Copyright And License
版权所有 © 2018,Jeffrey Schwartz
。 根据 MIT 许可证
发布。
A Cache Buster Called Buster
Buster busts your browser cache problems!
Version
1.0.0
Features
Cache busts your project's files in place.
Fingerprints (renames) files using MD5 hash-based cache busting file names.
Replaces references in files to original file names with their MD5 hash-based file names.
Optionally outputs a manifest file to buster.manifest.json.
Simple and intuitive configuration using .buster.json.
Invokable via the command line and scriptable.
Easily integrates into your project workflow.
Installation
Install Globally
$ npm install -g @4awpawz/buster
Install Locally
$ npm install --save-dev @4awpawz/buster
Buster Primer
Project Relative File Paths And Site Relative URLs
In the documentation that follows, references are made to project relative file paths and to site relative URLs.
"Project relative file paths" pertain strictly to your project's file structure. They are used to declare the input in operational directives when declaring the file paths to assets in your project that you want targeted by Buster for cache busting.
"Site relative URLs" pertain strictly to your website's runtime environment and are used to reference assets throughout your site (e.g. the src attribute of an img tag, the href attribute of a link tag, the URL() CSS function declared inside of a CSS stylesheet).
The important thing here is to understand that in order for Buster to perform its cache busting you, the developer, must insure that your site employs site relative URLs when referencing its assets. This is because Buster converts your project relative file paths to site relative URLs which it then uses to search the content of your site's files for site relative URLs that need to be updated to point to the assets it has fingerprinted with unique hashes.
A Typical Buster Work Flow
Your development build tool generates your production ready site (as opposed to development) into your project's release folder. When configuring Buster to cache bust your site, you would target your project files in the release folder by using project relative file paths in your Buster configuration's operational directives. Then from the root of your project you can use the command line to run Buster to cache bust your site in the release folder. You can then run your site from the release folder to insure that it is functioning as expected and once it is determined that it is functioning as expected you can then deploy your site directly from the release folder to its server using a command line utility such as rsync.
In a typical website project with the following or similar project structure
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.jpg
|- |- |- index.html
|- |- .buster.json
the project relative file path used in an operational directive to target housecat.jpg would be release/media/housecat.jpg and the site relative URL used to identify the image file in the browser would be media/housecat.jpg.
Operational Directives
Buster employs a concept called an Operational Directive, abbreviated od, which you declare in your .buster.json configuration file and which Buster uses to direct the operations it performs on your project's files. Each od is comprised of 2 parts, an input, and an operation.
Input
A project relative file path to one or more files.
Supports globs/wildcard patterns.
Important Buster assumes that all project relative file paths are relative to
process.cwd()
.Important Buster implements its glob support using node package glob. Please refer to node package glob should you need additional information on using globs with Buster.
Operation
Indicates the actions that Buster is to perform on the od's input file(s). It is a number preceded by a colon which separates the number from the input (e.g. ":1"). The following 3 operations are currently supported:
:1
Apply this operation only to those files whose own file names are to be fingerprinted for cache busting purposes (e.g. .jpg, .gif, .map
).
The format of each unique MD5 hash-based file name will be [original file's base name].[unique hash].[original file's extension] (e.g. cat.[unique hash].jpg
). Should the original file's base name contain 1 or more periods (e.g. main.js.map) the format of the MD5 hash-based file name will, as an example, be main.[unique hash].js.map.
:2
Apply this operation only to those files whose contents are to be searched for site relative URLs that point to assets whose file names have been fingerprinted and therefor need to be updated and whose own file names are not to be fingerprinted for cache busting purposes.
:3
Apply this operation only to those files whose own file names are to be fingerprinted for cache busting purposes (e.g. .jpg, .gif, .map
) and whose contents are to be searched for site relative URLs that point to assets whose file names have been fingerprinted and therefor need to be updated.
The format of each unique MD5 hash-based file name will be [original file's base name].[unique hash].[original file's extension] (e.g. cat.[unique hash].jpg
). Should the original file's base name contain 1 or more periods (e.g. main.js.map) the format of the MD5 hash-based file name will, as an example, be main.[unique hash].js.map.
Operational Directive Examples
Example Operational Directives Using Project Relative File Path:
Given the following project structure
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.jpg
|- |- |- index.html => contains img tag with a site relative url for its src i.e. <img src="/media/housecat.jpg">
|- |- .buster.json
and running Buster from the command line in the myproject folder with the following operational directives
`release/media/housecat.jpg:1`
`release/index.html:2`
will result in the following:
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.[unique hash].jpg
|- |- |- index.html => now contains img tag whose src attribute points to hashed img i.e. <img src="/media/housecat.[unique hash].jpg">
|- |- .buster.json
Example Operational Directives Using Project Relative File Paths And Globs:
Given the following project structure
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.jpg
|- |- |- |- purringcat.jpg
|- |- |- |- bigcats/
|- |- |- |- |- lion.jpg
|- |- |- |- |- tiger.jpg
|- |- |- index.html => contains img tags with site relative urls for its src e.g. <img src="/media/housecat.jpg">, <img src="/media/bigcats/lion.jpg">
|- |- .buster.json
and running Buster with the following directives
`release/media/**/*.jpg:1
`release/**/*.html:2`
will result as follows:
|- myproject
|- |- release/
|- |- |- media/
|- |- |- |- housecat.[unique hash].jpg
|- |- |- |- purringcat.[unique hash].jpg
|- |- |- |- bigcats/
|- |- |- |- |- lion.[unique hash].jpg
|- |- |- |- |- tiger.[unique hash].jpg
|- |- |- index.html => now contains img tags whose src attributes point to hashed img i.e. <img src="/media/housecat.[unique hash].jpg">, <img src="/media/bigcats/lion.[unique hash].jpg">
|- |- .buster.json
buster.json Configuration
Important Buster expects .buster.json to reside in your project's root folder, alongside package.json.
{
"options": {
"manifest": true,
"verbose": true,
"ignore": "media/original/**/*.jpg,media/original/**/*.gif"
},
"directives": [
"release/media/**/*.jpg:1",
"release/./index.html:2",
"release/css/test.css:3",
"release/script/test.js:3"
]
}
Options
Buster supports the following configuration options:
ignore
A quoted list of one or more comma separated project relative file paths to files that are to be ignored, defaults to ""
.
Supports globs and wildcard characters patterns.
manifest
A boolean, true
to save the manifest to buster.manifest.json in the project's root folder, defaults to false
.
verbose
A boolean, true
to output verbose logging, defaults to false
.
Typical Workflows
Using Buster In Node Projects
When using Buster in a Node project, install Buster locally:
~/Development/myproject > $ npm install --save-dev @4awpawz/buster
Then create .buster.json in your project's root folder, alongside package.json.
{
"directives": [
"release/media/**/*.jpg:1",
"release/css/**/*.css.map:1",
"release/scripts/**/*.js.map:1",
"release/**/*.html:2",
"release/css/**/*.css:3",
"release/scripts/**/*.js:3"
]
}
Then create an NPM script to call buster to cache bust your site:
"scripts": {
"bust": "buster"
}
From the root folder of your project, enter the following to cache bust your project:
~/Development/myproject $ npm run bust
Calling Buster From A Script
Buster can be called from a script, allowing it to be used as part of a greater workflow.
Scripting Buster to cache bust your project:
const buster = require("@4awpawz/buster");
const paramsConfig = {
options: {
manifest: true
},
directives: [
"release/media/**/*.jpg:1",
"release/css/**/*.css.map:1",
"release/scripts/**/*.js.map:1",
"release/**/*.html:2",
"release/css/**/*.css:3",
"release/scripts/**/*.js:3"
]
}
await buster(paramsConfig);
Filing Bugs And Feature Requests
- https://github.com/4awpawz/buster/issues
Changelog
v1.0.0
This is the first major release of Buster and incorporates many breaking changes from prior versions. Most notably, prior versions had a "safe mode" configuration option that would instruct Buster to cache bust "in place", meaning that it would not create backups and would not be able to restore files to their prior state. As it turns out, the vast majority of Buster's users are using "safe mode" because it fits their workflow of generating their site into a dedicated folder that can be cache busted and that could easily be repopulated by just regenerating the site. These changes were implemented to refactor Buster to precisely match this typical workflow. You can read more about the decision to refactor Buster at https://gettriossg.com/blog/news/2021/03/23/next-feature-release/.
v0.3.1
This release addresses fixes for security warnings for packages used internally by Buster only. There are no changes to the code base.
v0.3.0
This release addresses one bug and fixes for security warnings for packages used internally by Buster only. Also landing with this release is reduced console output; use the verbose
config option if needed.
Major bug fixes:
- Addresses issue
#14
which could cause Buster to mangle hashed file names. Please note that beginning with this release, Buster now generates hashed file names as [hash]-[file name].[file extension]. You are strongly advised to upgrade your projects and rebuild them.
v0.2.4
This release addresses fixes for security warnings for packages used internally by Buster only. There are no changes to the code base.
v0.2.3
Major bug fixes:
Addresses issue
#13
which would cause Buster to crash when reading a configuration file that doesn't exist.Addresses issue
#12
which would cause Buster to crash when setting paramsConfig to a default value of{}
to indicate that it wasn't passed.
v0.2.2
This release includes no changes to the code base.
- Addresses issue
#11
which seeks to lockdown all project dependencies including descendants using NPM'sshrinkwrap
.
v0.2.1
Major and minor bug fixes - includes but not limited to the following:
Addresses issue
10
which would cause buster to fail when reading command line configuration data belonging to the application that launched it with paramsConfig.Addresses issue
#9
which would sometimes causerestore
to fail. This fix totally replaces the one introduced in v0.2.0, and now handles the issue earlier in the restore processing cycle.
v0.2.0
Major refactor - includes but not limited to the following:
Introduces experimental "safe mode" feature, resolves
#6
.v0.1.6 breaks handling of backup files bug, fixes
#5
.Removes hashed files from the manifest returned by glob during restore.
Implements new resolution of destination paths.
Removes the "file-exists" package from the project.
Catching some async exceptions to prevent unresolved promise exceptions.
Configuration attempts to resolve from paramsConfig (i.e. passed via a script) first.
Updated README.md
v0.1.6
Addresses a bug in command-line processing which would cause Buster to crash when the user enters only "bust" or "restore" from the command-line.
Addresses a bug in od processing which would cause Buster to crash when attempting to create folders that already exist.
Addresses a bug in od processing which would cause Buster to crash when attempting to delete files that no longer exist.
Copyright And License
Copyright © 2018, Jeffrey Schwartz
. Released under the MIT license
.