README

使用 Statamic 生成静态站点。

安装

您可以使用以下命令安装 Static Site Generator 包

php please install:ssg

该命令将通过 Composer 安装 statamic/ssg 包，可选地发布配置文件，并提示您是否希望安装用于运行多个工作者的 spatie/fork 包。

用法

运行以下命令

php please ssg:generate

您的网站将生成到一个目录中，您可以按需部署。以下列出了部署示例以供参考。

多个工作者

为了提高性能，您可以将页面生成分散到多个工作者上。这需要 Spatie 的 Fork 包。然后您可以指定要使用多少个工作者。您可以使用与 CPU 核心数相同数量的工作者。

composer require spatie/fork
php please ssg:generate --workers=4

路由

路由将不会自动生成。您可以通过在配置文件中的 urls 数组中添加任何您希望生成的额外 URL 来添加它们。

'urls' => [
    '/this-route',
    '/that-route',
],

您还可以排除单个路由或带有通配符的路由组。这将覆盖 urls 配置中的任何内容。

'exclude' => [
    '/secret-page',
    '/cheat-codes/*',
],

动态路由

您可以通过向 addUrls 方法提供一个返回数组的闭包来动态添加 URL。

use Statamic\StaticSite\SSG;

class AppServiceProvider extends Provider
{
    public function boot()
    {
        SSG::addUrls(function () {
            return ['/one', '/two'];
        });
    }
}

分页路由

在您的 Antlers 模板中检测到分页的地方（例如，如果在 collection 标签上使用 paginate 参数），将自动生成多个页面，URL 样式为 /articles/page/2。

您可以在 config/statamic/ssg.php 中配置自定义路由样式。

'pagination_route' => '{url}/{page_name}/{page_number}',

生成后的回调

您可以选择定义在网站生成后要执行的额外步骤。

use Statamic\StaticSite\SSG;

class AppServiceProvider extends Provider
{
    public function boot()
    {
        SSG::after(function () {
            // eg. copy directory to some server
        });
    }
}

Glide 图片

Statamic 的默认配置是让 Glide 使用 "动态" 图片，这意味着 glide 标签只会输出 URL。图片本身将在访问 URL 时生成。对于静态网站，这不再有意义，因为通常它将被部署在没有任何动态 Glide 路由的地方。

默认情况下，SSG 会自动重新配置 Glide，以便在使用 glide 标签时将图片生成到 img 目录。这实际上是 Glide 的自定义静态路径选项。

您可以自定义图片的生成位置

'glide' => [
    'directory' => 'images',
],

如果您正在使用自定义 glide 磁盘，您可以告诉 SSG 不要修改它

'glide' => [
    'override' => false,
],

然后在生成完成后复制图片（或创建符号链接）

SSG::after(function () {
    $from = public_path('img');
    $to = config('statamic.ssg.destination').'/img';

    app('files')->copyDirectory($from, $to);
    // or
    app('files')->link($from, $to);
});

触发命令失败

如果您在 CI 环境中使用 SSG，您可能希望防止命令在生成任何页面时成功（例如，防止部署不完整的网站）。

默认情况下，即使有未生成的页面，命令也会成功完成并退出。您可以配置SSG在出现错误时提前失败，甚至在警告时也失败。

'failures' => 'errors', // or 'warnings'

部署示例

以下示例假设您的工作流程是在本地编写内容，而不是在生产中使用控制面板。

部署到 Netlify

部署由提交到Git并推送到GitHub触发。

在您的 Netlify 账户中创建一个站点
将站点链接到您想要的GitHub仓库
添加构建命令 php please ssg:generate（如果您需要编译css/js，请确保添加该命令并在生成静态站点文件夹之前执行它。例如，npm install && npm run build && php please ssg:generate）。
设置发布目录 storage/app/static

当您的站点有 APP_URL...

将其设置为环境变量。添加 APP_URL https://thats-numberwang-47392.netlify.com

最后，在本地使用 php artisan key:generate 生成一个 APP_KEY 并复制其值，然后...

将其设置为环境变量。添加 APP_KEY [您的应用密钥值]

S3 资产容器

如果您将资产存储在S3桶中，使用的.env需要与Laravel默认值不同，因为它们已被Netlify保留。例如，您可以修改如下

# .env
AWS_S3_ACCESS_KEY_ID=
AWS_S3_SECRET_ACCESS_KEY=
AWS_S3_DEFAULT_REGION=
AWS_S3_BUCKET=
AWS_URL=

确保还更新了您的s3磁盘配置中的这些内容

// config/filesystems.php
's3' => [
    'driver' => 's3',
    'key' => env('AWS_S3_ACCESS_KEY_ID'),
    'secret' => env('AWS_S3_SECRET_ACCESS_KEY'),
    'region' => env('AWS_S3_DEFAULT_REGION'),
    'bucket' => env('AWS_S3_BUCKET'),
    'url' => env('AWS_URL'),
],

部署到 Vercel

部署由提交到Git并推送到GitHub触发。

创建一个名为 ./build.sh 的新文件，并将下面的代码片段粘贴进去。
在您的终端上运行 chmod +x build.sh 以确保文件在部署时可以被执行。
在您的 Vercel 账户中导入一个新的站点
将站点链接到您想要的GitHub仓库
添加构建命令 ./build.sh
设置输出目录为 storage/app/static
在项目设置中添加环境变量：APP_KEY <从开发中复制 & 粘贴>

build.sh 代码

将以下代码片段添加到 build.sh 文件中，以安装PHP、Composer并运行 ssg:generate 命令

#!/bin/sh

# Install PHP & WGET
yum install -y amazon-linux-extras
amazon-linux-extras enable php7.4
yum clean metadata
yum install php php-{common,curl,mbstring,gd,gettext,bcmath,json,xml,fpm,intl,zip,imap}
yum install wget

# INSTALL COMPOSER
EXPECTED_CHECKSUM="$(wget -q -O - https://composer.github.io/installer.sig)"
php -r "copy('https://getcomposer.org.cn/installer', 'composer-setup.php');"
ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"

if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]
then
    >&2 echo 'ERROR: Invalid installer checksum'
    rm composer-setup.php
    exit 1
fi

php composer-setup.php --quiet
rm composer-setup.php

# INSTALL COMPOSER DEPENDENCIES
php composer.phar install

# GENERATE APP KEY
php artisan key:generate

# BUILD STATIC SITE
php please ssg:generate

部署到 Surge

先决条件：使用 npm install --global surge 安装。您的第一次部署将涉及通过命令行创建账户。

使用命令 php please ssg:generate 构建
使用 surge storage/app/static 部署

部署到 Firebase hosting

先决条件：按照说明进行操作，以开始使用Firebase hosting

一旦设置好托管，请确保您的 firebase.json 中的 public 配置设置为 storage/app/static
(可选) 添加 predeploy 配置以运行 php please ssg:generate
运行 firebase deploy

statamic / static-site-generator

维护者

详细信息