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 hncore/basset
php artisan basset:install

可选发布配置文件。

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

注意
Basset默认在本地环境中禁用。如果您想更改它，请将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 命令

从 CDNs 复制资产到您的服务器可能需要一些时间，这取决于资产的大小。对于大型页面，这甚至可能需要整整几秒钟。您可以通过一次性内部化所有资产来轻松防止这种情况发生。您可以使用 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 可用

• 在 Basset 可以工作的情况下，在生产环境中运行 php artisan storage:link 是强制性的；因此，建议您将其添加到 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文件中加载，它也只会加载资源一次。

常见问题解答（FAQ）

Basset无法正常工作，可能是什么原因？

在做出任何更改之前，您可以运行命令php artisan basset:check。它将执行基本的测试以初始化、写入和读取资源，让您更好地了解任何错误。

Basset失败的最常见原因：

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

2. 磁盘配置不正确。
   默认情况下，Basset使用Laravel的public磁盘。对于新的Laravel项目，配置通常是正确的。如果您正在升级项目或更改了public磁盘配置，建议您将config/hncore/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。

安全

如果您发现任何与安全相关的问题，请通过电子邮件发送到 hello@hncoreforlaravel.com，而不是使用问题跟踪器。

致谢

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

许可协议

MIT。请参阅许可文件获取更多信息。