README

轻松使用CSS/JS等资源，无论它们在哪里，而不仅仅是您的公共目录

{{-- if you're used to Laravel's asset helper: --}}
<link href="{{ asset('path/to/public/file.css') }}">

{{-- just change asset() to basset() and you can point to non-public files too, for example: --}}
<script src="{{ basset(storage_path('file.js')) }}">
<script src="{{ basset(base_path('vendor/org/package/assets/file.js')) }}">
<script src="{{ basset('https://cdn.com/path/to/file.js') }}">

只需这样做。 Basset会从任何位置下载文件到storage/app/public/bassets，然后输出资源的公共路径。

使用Basset，您可以轻松地内部化和使用

• 来自外部URL的文件（如CDN）
• 来自内部但非公共URL的文件（如供应商目录）
• 来自外部URL的整个存档（如GitHub）
• 来自本地非公共路径的整个目录（如其他本地项目）

不再需要发布包文件。不再仅使用NPM下载文件。在HTTP/2和HTTP/3的时代，这是一个简单而有效的解决方案。

安装

composer require backpack/basset
php artisan basset:install

可选 发布配置文件。

php artisan vendor:publish --provider="Backpack\Basset\BassetServiceProvider"

注意
Basset默认在本地环境中禁用。如果您想更改它，请在您的env文件中设置BASSET_DEV_MODE=false。

存储符号链接

Basset使用public磁盘来存储缓存资源，在公开可访问的目录中。因此，您需要运行php artisan storage:link来创建符号链接。安装命令将要求您运行该命令，并将其添加到您的composer.json中。这将在您的开发/预发布/生产服务器上最有可能是正确的。如果不是这样，请确保您手动在任何需要的地方创建链接，使用命令php artisan storage:link。

磁盘

默认情况下，Basset使用public磁盘。如果您发现资源在页面上没有显示，您可能有一个旧的Laravel配置。请确保您的磁盘在config/filsystems.php上设置正确——它应该看起来像默认配置。

用法

basset() 助手

您可以直接使用basset()助手而不是Laravel的asset()助手，并指向CDN和非公共文件。使用Laravel的路径助手构建文件的绝对路径，然后Basset将处理其余部分。

来自CDN的本地文件

{{-- instead of --}}
<link href="{{ asset('path/to/public/file.css') }}">

{{-- you can do --}}
<link href="{{ basset('path/to/public/file.css' }}">
<link href="{{ basset('https://cdn.com/path/to/file.css') }}">
<link href="{{ basset(base_path('vendor/org/package/assets/file.css')) }}">
<link href="{{ basset(storage_path('file.css')) }}">

Basset将

• 从供应商目录将该文件复制到您的storage目录（即内部化文件）
• 对所有请求使用内部化的文件

@basset() 指令

对于CSS、JS、图像和视频等已知的资源类型，Basset使其加载资源更加简洁。不需要编写HTML来为<script>、<link>或<img>创建，只需使用@basset()指令，所有必要的HTML都会为您输出

{{-- instead of --}}
<script src="{{ asset('path/to/public/file.js') }}">
<link href="{{ asset('path/to/public/file.css') }}">
<img src="{{ asset('path/to/public/file.jpg') }}">
<object data="{{ asset('path/to/public/file.pdf') }}"></object>

{{-- you can do --}}
@basset('https://cdn.com/path/to/file.js')
@basset('https://cdn.com/path/to/file.css')
@basset(resource_path('/path/to/file.jpg'))
@basset(resource_path('/path/to/file.pdf'))

以下是已知的文件类型；

Basset将

• 从供应商目录将该文件复制到您的storage目录（即内部化文件）
• 对所有请求使用内部化的文件
• 确保该文件在每次页面加载时只加载一次

@bassetBlock() 指令

轻松将代码块移动到文件中，以便它们被缓存

+   @bassetBlock('path/or/name-i-choose-to-give-this')
    <script>
      alert('Do stuff!');
    </script>
+   @endBassetBlock()

Basset将

• 在storage/app/public/basset目录中创建一个包含该JS代码的文件（即内部化代码）
• 在所有请求中，使用本地文件（使用<script src="">）而不是将JS内联
• 确保该文件在每次页面加载时只加载一次

@bassetArchive() 指令

轻松使用存档资源（.zip & .tar.gz）

+    @bassetArchive('https://github.com/author/package-dist/archive/refs/tags/1.0.0.zip', 'package-1.0.0')
+    @basset('package-1.0.0/plugin.min.js')

Basset将

• 将存档下载到您的 storage/app/public/basset 目录（即内部化代码）
• 解压它
• 在所有请求中，使用本地文件（使用 <script src="">）
• 确保该文件在每次页面加载时只加载一次

注意：当引用 .zip 存档时，需要 PHP zip 扩展。

@bassetDirectory() 指令

轻松内部化和使用整个非公开目录

+    @bassetDirectory(resource_path('package-1.0.0/'), 'package-1.0.0')
+    @basset('package-1.0.0/plugin.min.js')

Basset将

• 将该目录复制到您的 storage/app/public/basset 目录（即内部化代码）
• 在所有请求中，使用内部化文件（使用 <script src="">）
• 确保该文件在每次页面加载时只加载一次

basset 命令

从 CDN 复制资产到服务器可能需要一些时间，具体取决于资产大小。对于大型页面，这甚至可能需要几秒钟。您可以轻松地一次性内部化所有资产来防止这种情况发生。您可以使用 php artisan basset:cache 遍历所有 blade 文件，并内部化所有可能的文件。如果需要，basset:clear 将删除所有文件。

php artisan basset:cache         # internalizes all @bassets
php artisan basset:clear         # clears the basset directory

为了加快生产环境中的首次页面加载速度，我们建议您将 php artisan basset:cache 命令添加到您的部署脚本中。

Basset 缓存事件

如果您需要在每个资产缓存后进行自定义操作，您可以在 EventServiceProvider 中设置对 BassetCachedEvent 的监听器。每次资产被缓存时都会触发此事件。

配置

请参阅 配置文件 以获取所有配置选项。注意，其中一些配置项也有 ENV 变量，因此您可以

• 使用 BASSET_DEV_MODE=false 启用/禁用开发模式 - 这将强制 Basset 即使在本地主机上也内部化资产
• 使用 BASSET_DISK=yourdiskname 更改资产内部化的磁盘
• 使用 BASSET_CACHE_MAP=false 禁用缓存映射（在无服务器如 Laravel Vapor 上需要）

部署

Laravel 应用程序有许多部署选项，但我们将尝试在这里涵盖最流行的一些部署陷阱

VPS / SSH / Composer 可用

• 在生产环境中运行 php artisan storage:link 是强制性的，以便 Basset 能够工作；因此建议您将其添加到 composer.json 的脚本部分，无论是 post-composer-install 还是 post-composer-update；
• 建议在每次部署后运行 php artisan basset:fresh；因此建议您将其添加到 composer.json 的脚本部分，位于 post-composer-update；

Laravel Forge

它只是一个托管的 VPS，因此请参阅上述内容。

Laravel Vapor

第1步。 在您的 vapor.yml 中包含 storage: yourbucketname

第2步。 在您的 Vapor .ENV 文件中确保您有

BASSET_DISK=s3
BASSET_CACHE_MAP=false

(可选) 在您部署到 Vapor 之前，您可能想在本地上设置 S3 以测试它是否工作。如果您这样做，这些步骤可能会有所帮助。如果您在 Vapor 上部署时遇到问题（尤其是通过 GitHub actions），这里有一些 提示。

FTP / SFTP / ZIP

如果您通过从本地上传项目进行部署（无论是手动还是自动），您应该

• 确保存在由 php artisan storage:link 创建的别名；否则，您的别名可能指向一个不存在的本地主机路径；或者，您可以在其配置中更改 Basset 使用的磁盘。
• 每次部署前，请确保禁用开发模式（在您的 .ENV 文件中设置 BASSET_DEV_MODE=false），然后运行 php artisan basset:fresh；这将确保您的本地主机下载所有资产，然后您再将它们上传到压缩包中；

这个包为什么存在？

1. 保留CDN依赖的副本在您的本地。

出于许多原因，您可能想要避免CDN，CDN有时可能会失败，可用性不是100%，或者您的应用程序可能需要离线工作。

1. 忘记编译您的资产。

大多数时候，后端开发者会与npm和编译依赖项纠缠不清。Backpack已经做到了这一点，在某个时候，我们的主要仓库中有近100Mb的资产。Basset将所有这些混乱从后端开发者那里清除。

1. 避免重复加载相同的资产。

在Laravel中，如果您的CSS或JS资产在blade文件中加载

// card.blade.php

<div class="card">
  Lorem ipsum
</div>

<script src="path/to/script.js"></script>

并且您在每个页面上多次加载该blade文件（例如，在每个页面上多次包含 card.blade.php），您最终会在同一页面上多次加载该 script 标签。为了避免这种情况，Laravel 8提供了@once 指令，它只会输出一次，不管该blade文件加载了多少次

// card.blade.php

<div class="card">
  Lorem ipsum
</div>

@once
<script src="path/to/script.js"></script>
@endonce

但是，如果您的 script.js 文件不仅被 card.blade.php 加载，而且还被其他blade模板（例如，同一页面上加载的 hero.blade.php）加载呢？如果您使用的是 @once 指令，您将再次遇到相同的问题 - 同一个脚本被多次加载。

这就是这个包发挥作用的地方。它只会加载资产一次，即使它是从多个blade文件中加载的。

常见问题解答

Basset无法正常工作，可能出了什么问题？

在做出任何更改之前，您可以使用命令 php artisan basset:check。它将执行基本测试以初始化、写入和读取资产，为您提供有关任何错误的更好见解。

Basset失败的最常见原因是

1. .env 文件中的 APP_URL 设置不正确。
   确保您的 .env 中的 APP_URL 与您的服务器配置相匹配，包括主机名、协议和端口号。设置不正确可能导致资产加载问题。

2. 磁盘配置不正确。
   默认情况下，Basset使用Laravel的 public 磁盘。对于新的Laravel项目，配置通常是正确的。如果您正在升级项目或更改了 public 磁盘配置，建议您在 config/backpack/basset.php 中更改basset磁盘为 basset。该 basset 磁盘是原始Laravel public 的副本，具有正常配置。

3. 缺少或损坏的存储符号链接。
   如果您使用的是默认的 public 磁盘，Basset需要使用 php artisan storage:link 命令创建存储和公开访问文件夹之间的符号链接。在安装期间，Basset会尝试创建符号链接。如果失败，您需要手动使用 php artisan storage:link 创建它。如果遇到问题（例如，在移动项目后），重新创建符号链接应该可以解决它们。

Homestead用户的注意：符号链接不能在虚拟机内部创建。您应该使用： vagrant down 停止您的实例，在您的本地应用程序文件夹中创建符号链接，然后使用 vagrant up 将系统恢复。

变更日志

请参阅发布标签以获取有关最近更改的更多信息。

测试

$ composer test

贡献

请参阅contributing.md 以获取详细信息以及待办事项列表。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件发送至 [email protected]，而不是使用问题跟踪器。

致谢

• Antonio Almeida
• Cristian Tabacitu
• 所有贡献者

许可证

MIT。有关更多信息，请参阅 许可证文件。