README

VMLY&;R 的 Drupal 9 KIT 是一个帮助构建和维护 Drupal 9 项目的发行版。

关于 KIT
入门指南
安装后和与供应商相关的配置
注意事项和建议
主题开发

关于 KIT

通过一系列 Docksal 命令、安装配置文件和基础主题，该发行版提供了以下支持：

常用模块
Composer 项目框架
Docksal 命令套件
使用 Docksal 进行 CI 和构建过程
Drupal 网站配置
多环境配置和开发
多站点配置和开发
标准化的主题管理和结构

常用模块 + composer.json

KIT 使用 composer 处理项目依赖。默认情况下，该发行版包含了一些模块和库。该列表是根据以下标准确定的：

最佳实践 – Drupal 9 核心比 Drupal 7 出厂时更具可行性，但仍有某些模块和配置是我们需要并且应该为每个网站使用，包括支持多个环境。例如，Blazy 用于懒加载图片，高级聚合用于更好的样式/脚本管理，配置同步 + 配置拆分（而不是 Features）。
标准化 – 由于是开源项目，Drupal 有多个模块针对类似问题的解决方案。我们已默认添加了一些项目到列表中，以帮助标准化处理某些问题的工具，例如在实体上包含视图的字段。

Composer 项目框架

KIT 通过添加自己的框架来强制执行结构，该框架在 composer 安装和更新后运行 Drupal 的默认框架。Drupal 的框架会自动擦除并重新复制文件，这些文件从 Drupal 核心复制到公共目录（如 default.settings.php、htaccess、robots.txt 等）。VMLY&;R 还创建标准配置文件夹结构，并删除或更新应该通过补丁修改（如 .htaccess）或编译（如 drupal.settings.additional.php 编译到 drupal.settings.php）而不是直接签入存储库的文件。

Docksal 命令套件

项目使用 Docksal 进行本地环境开发和项目构建。以下是项目中包含的 Docksal 命令列表

init – 通常在构建或重建项目和其依赖项时使用。该命令将启动 docksal，下载依赖项，确保项目相关网站目录和数据库存在，构建前端工件，并从另一个环境导入数据库。该命令接受可选参数 builder，详细说明如下“Docksal + CI 和构建过程”部分。
init-deps – 当项目依赖项需要重新下载和安装时使用。目前包括 Composer 和 NPM。
init-services – 当项目相关的命令和工具依赖项需要重新下载和安装时使用。目前包括在容器中验证 nvm、npm 和 node 是否可用。
k – 一个简单的包装命令，使其更容易运行 kit 命令。例如，fin k gulp 而不是 fin kit/gulp。
pre-deploy – 在需要预部署清理/修改的情况下使用。目前用于从构建工件中删除不需要在外部环境中存在的文件。

通过 vmlyr-drupal/kit-docksal-commands 包包含额外的命令，并在 docksal 命令目录下的 "kit" 子目录中安装。安装 composer 后，请参阅该目录中的 README.md 文件以获取有关这些命令的更多信息。

Docksal + CI 和构建流程

Docksal 和 KIT 的命令可用于运行构建流程。通过运行 ci 命令切换 "CI 模式"：fin init ci。当 docksal 用于创建要发布的构建文件时，这是最好的使用方式。默认情况下，构建器以 --no-dev 模式运行 composer，并自动删除与构建相关的文件等。

Drupal 网站配置

此 composer 项目包含 2 个由 VMLY&＆R 创建的 Drupal 配置文件

双翼飞机 – 此配置文件默认安装和设置了大量的网站配置和相关模块。除了与最佳实践和标准化相关的项目外，它相当基础，但确实处理了安装新 Drupal 实例时的大量单调工作。一些例子包括
- 默认环境（本地、远程开发、远程测试、远程生产）及其相关的配置分割和设置以及模块。
- 默认修改/删除的核心文件，如 .htaccess https 覆盖、默认 settings.php 变更、使用 RobotsTXT 模块而不是包含的核心文件等。
- 与灯塔相关的设置，如图像优化、响应式图像 + 焦点，高级聚合、Blazy 等。
- 各种设置以及在新网站上上线所需的内容，如为生产实例设置高级聚合、全局和节点页面的默认元标签、XML 网站地图默认值、禁用匿名用户注册等。
黑鸟 – 此配置文件基于 双翼飞机 配置文件，但有点更具有观点。它包括有用的段落组件、图像样式、媒体实现等大量额外配置。要充分利用这些额外组件，请确保运行 fin kit/theme 并基于同名 "Blackbird" 选项生成新的主题。

多环境配置和开发

多环境配置作为分发的一部分通过默认 settings.php 文件和 双翼飞机 和黑鸟配置文件预配置。

环境 + settings.php 文件

每个网站默认的 settings.php 文件 包含 /sites/environment.settings.php，该文件根据当前网站的环境切换相关配置的状态。远程环境，如由 Acquia、Pantheon 或 Platform.sh 托管的环境，有 $_ENV 或 $_SERVER 变量，这些变量告知网站它处于某个环境并启用某些配置或设置。当在本地工作于网站时，所有配置分割都应表示为 "不活跃"。只有通过 fin 命令 conf 在导出/导入时启用 "local" 配置分割状态。这确保了配置可以定期导出，而不会让某个环境意外优先。

开发和 docksal 设置文件通过 environment.settings.php 文件自动包含，如果存在的话。这些文件由 git 忽略，对于禁用缓存或允许详细错误报告等开发覆盖很有帮助。由 composer 运行的 KitScriptHandler 脚本自动将 settings.local.php 和 settings.docksal.php 复制到每个网站目录，以更好地协助本地开发。

环境 + VMLY&＆R 配置文件双翼飞机和黑鸟

VMLY&＆R 配置文件默认包含配置分割选项，并在安装期间执行附加任务以建立默认配置和每个分割的配置，以及安装完成之前作为本地环境导入。

包含的四个默认配置包括

本地（local） – 本地开发配置覆盖，例如禁用页面缓存和高级聚合，并启用开发模块。
开发（remote_dev） - 主要启用 Shield 认证和 Stage File Proxy。
阶段（remote_stage）- 主要启用 Shield 身份验证和阶段文件代理。
生产（remote_prod）- 启用 Syslog 和表单验证码。

多站点支持

通过我们提供的 Docksal 工具，多站点支持已集成到项目中。当需要添加其他站点时，只需创建新的 drush 别名文件并运行 composer install。该命令将构建站点文件夹结构，将默认的 settings.php 文件复制到站点目录，然后即可进行安装。kit/sync 和 kit/conf 工具都支持在多站点 Drupal 实例中同步和导出/导入任何站点。

标准化的主题管理和结构

KIT 自动包含一个基础主题（Bazo）和两个基于 Bazo 的脚手架主题。

Bazo 基础主题

Bazo 基础主题旨在帮助辅助其子主题。它包括标准模板，但将大多数类移动到其预处理中，以便子主题预处理可以更轻松地删除。子主题的两个更重要因素是

自动 Drupal 库附加 - 只要遵循命名约定，Bazo 就会自动将子主题库附加到相关实体上
- theme-name/entity-id
- theme-name/entity-id--view-mode
- theme-name/entity-id--view-mode--bundle
这不仅有助于您的项目保持组织结构，而且允许前端开发者在不接触 PHP 的情况下将库附加到组件上。

注意：请注意 entity-id--view-mode--bundle 与 Drupal 默认的 entity-id--bundle--view-mode 主题名称约定不同。这是故意为之的，因为通常同一视图模式的所有捆绑包都会共享一个库，而所有视图模式都会共享一个特定捆绑包的库。这允许为视图模式包含一个通用库，然后包含更具体的、针对特定捆绑包的实现。
自动属性变量转换 - Baso 自动将指定的数组转换为 "后处理" 函数中的属性变量，这些变量列在预处理器的 $variables['#attribute_variables'] 数组中。例如
- $variables['#attribute_variables'][] = 'figcaption_attributes';
- $variables['#attribute_variables'][] = 'wrapper_attributes';
- $variables['#attribute_variables'][] = 'figcaption_attributes';
- $variables['#attribute_variables'][] = 'image_attributes';

通过 Docksal 命令构建脚手架子主题

VMLY&R 包含几个脚手架主题，可以从中构建，但它们不是直接包含在项目中。相反，可以通过 fin kit/theme 命令生成。

安装

对于一个项目来说，启动一个站点只需几个步骤。

如果尚未安装，请安装 Docksal。
安装项目。
1. 使用 composer 创建新项目。 注意：如果可能，尽量不要使用带有连字符的项目名称，因为 docksal 目前对带有连字符的项目存在奇怪的问题。
```
fin run-cli "composer create-project --no-install vmlyr-drupal/kit [FOLDER_NAME_HERE]"
```
2. 进入目录。
```
cd [FOLDER_NAME_HERE]
```
3. 如果此目录尚未是 git 项目，则初始化新仓库
```
git init
```
4. 如果此项目有远程仓库，则添加远程 origin
```
git remote add origin [REMOTE_REPOSITORY_URL_HERE]
```
在项目目录中运行 fin start 以创建 Docksal 项目。
打开每个站点的 Drush 别名文件（/drush/sites/ 以更新本地 URI 以及任何已知的关联服务器信息。 （注意：您应该已在运行 fin start 后由 Docksal 列出本地）

如果正在运行多站点安装，请打开 /sites/sites.php 文件夹，以确保域名已映射到正确的站点。

Docksal 的域名是项目文件夹名称，后跟 .docksal，为字母数字。例如 drupal-8-kit 变为 drupal8kit.docksal。

$sites['domainname.docksal'] = 'www';
$sites['www.domainname.docksal'] = 'www';

也在这里映射外部域名。

$sites['www.domainname.com'] = 'www';
$sites['dev-www.domainname.com'] = 'www';
$sites['stg-www.domainname.com'] = 'www';
$sites['prod-www.domainname.com'] = 'www';

Docksal 支持子域名，Drupal 也支持在多站点安装上映射子域名。

$sites['subdomain.domainname.docksal'] = 'subdomain';

也在这里映射外部子域名。

$sites['subdomain.domainname.com'] = 'subdomain';
$sites['dev-subdomain.domainname.com'] = 'subdomain';
$sites['stg-subdomain.domainname.com'] = 'subdomain';
$sites['prod-subdomain.domainname.com'] = 'subdomain';

运行 fin init
打开浏览器并访问站点；它应该被重定向到站点安装页面。
按照安装过程进行操作。（注意：选择配置文件后，网站应自动开始安装；如果没有自动安装并要求输入数据库设置，请在不添加任何GET参数的情况下重新加载/core/install.php URL）
填写网站配置。如果使用VMLY&R配置文件且不知道环境URL，最好猜测它们可能是什么（我们建议遵循//ENV-WWW.SITE_PROD.DOMAIN结构）。这些域名用于表示当前环境以及通过Stage File Proxy使用其他环境资源。现在设置这些有助于在开发过程中不需要在多个地方设置这些。
如果您选择了VMLY&R配置文件之一，在保存配置后，网站应将所有相关配置导出到网站的同步目录，并将其作为本地环境导入。
安装完成后，将重定向到网站主页。
要开始构建自己的主题，运行fin kit/theme以根据我们的示例骨架主题生成新的主题+主题源设置。如果已安装Blackbird配置文件，我们建议从同名的Blackbird主题选项进行构建。如果您不使用Blackbird并且想要为您的主题提供一个更简单的起点，我们建议从Biplane骨架主题进行构建。

安装后和与供应商相关的配置

根据托管提供商，可能需要创建或更新一些配置。同样，一些配置可能不再需要，可以删除。

Jenkins

@TODO Jenkins设置说明。

Bitbucket管道

要启用Bitbucket管道构建，将bitbucket-pipelines-example.yml重命名为bitbucket-pipelines.yml。注意：要在Bitbucket中工作，必须启用Bitbucket管道。

设置

在将管道文件复制到仓库后，需要在您的Bitbucket账户中进行一些配置，以便管道与您的外部仓库通信。

转到设置 > 管道 > 设置，并切换“启用管道”
转到设置 > 管道 > 仓库变量，并添加一个名为DESTINATION_REPOSITORY的变量，其值为您的托管提供商仓库的URL（例如：对于Pantheon，为ssh://codeserver.example.drush.in:2222/~/repository.git）
转到设置 > 管道 > 部署，并配置/创建您想要连接的部署环境。
- 重命名环境，确保它匹配您管道文件中的deployment键值（例如：deployment: Development）
- 在此处添加一个名为DESTINATION_REPOSITORY_BRANCH的变量，并将其值设置为要在您的托管提供商仓库中推送的分支（例如：master）。
转到设置 > 管道 > SSH密钥。这些密钥用于连接到您的托管提供商仓库。
- 生成一个密钥对。注意：Acquia需要比Bitbucket生成的默认密钥对更强的密钥对。您需要通过在本地终端中运行ssh-keygen -b 4096手动创建密钥对（考虑使用描述性的名称），然后将其私钥和公钥添加到Bitbucket中。
- 将公钥添加到托管提供商仓库上的用户。如果提供商支持，最好使用部署密钥，或者创建一个仅用于将提供商连接到管道的服务账户（例如：一个用户在提供商上，地址为pipelines@yourwebsite.com，专门用于维护与管道的连接）。
- 将托管提供商仓库的主机地址放入“已知主机地址”区域中的“主机地址”字段，然后获取指纹以验证连接。现在您应该能够推送更改并观察管道启动。

注意：有时可能需要尝试不同的方法来确保管道可以连接到托管提供商的仓库，例如重新创建密钥对。

提供默认管道

分支：Master

此管道监视主分支，当代码合并到其中时，将自动构建和部署代码到相关的“开发”环境仓库。

此管道使用默认的“构建包”和“部署包”管道步骤。“部署包”步骤默认为运行“开发”部署。

在应有一个开发分支构建到开发环境，而主分支构建到预发布或生产环境的情况下，将“部署”更改为相关环境名称，并创建一个新的基于分支的管道以推送至开发。

自定义：功能

此管道接受任何分支，并允许将构建推送到托管提供商仓库上的自定义“功能”分支。这允许在托管提供商上轻松创建“功能”环境。

此管道使用默认的“构建包”和“部署包”管道步骤。“部署包”步骤默认为运行“功能”部署，需要在Bitbucket Pipelines的“设置”>“管道”>“部署”选项卡下创建。

要运行此管道

转到您的Bitbucket账户的“分支”部分
单击您想构建的分支右侧的“...”
选择“运行分支管道”
选择“自定义：功能”管道
在“DESTINATION_REPOSITORY_BRANCH”字段中填写您希望在托管提供商仓库上的功能分支的名称（例如：feature/header-redesign）
单击“运行”

拉取请求

此管道在拉取请求上自动运行。它执行完整构建然后进行代码检查；如果有任何问题出现，则失败。

此管道使用默认的“构建包”和“测试包”管道步骤。它不部署代码。

包含在KIT中的文件

以下分组以提供哪些文件/目录可以修改或删除的上下文。

特定于提供商的文件：Acquia

/hooks/common
/hooks/dev
/hooks/prod
/hooks/samples
/hooks/test

特定于提供商的文件：AWS

/.ebextensions

特定于提供商的文件：Pantheon

/pantheon.yml
/scripts/pantheon/*

特定于提供商的文件：Platform

通用文件

/docroot/web.config（我们通常不使用ASP.NET；保留以备项目需要时使用）
/env.example（我们不推荐使用env文件；保留以备项目需要时使用）
/package.json（由packagist用于创建项目，不再需要）
/travis.yml（我们通常不使用travis；保留以备项目需要时使用）

特定于提供商的修改

根据所选的托管提供商对项目进行的修改。

特定于提供商的修改：Acquia

删除Acquia中不必要的文件和目录
Settings.php修改
1. 打开/docroot/sites/www/settings.php并找到“包含服务器特定配置”部分。
2. 取消注释Acquia部分。
3. 从其他提供商中删除不需要的服务器特定配置。

特定于提供商的修改：AWS

删除Platform.sh中不必要的文件和目录
Settings.php修改
1. 打开/docroot/sites/www/settings.php并找到“包含服务器特定配置”部分。
2. 取消注释AWS部分。
3. 相应地修改。
4. 从其他提供商中删除不需要的服务器特定配置。

特定于提供商的修改：Pantheon

删除Pantheon中不必要的文件和目录
将/docroot重命名为/web.
从已安装的站点目录到/sites/default/files创建符号链接
1. cd到/sites/www（或如果是多站点，其他站点目录）。
2. 运行rm -rf files以删除当前文件目录。
3. 运行 ln -s ../default/files files 以创建指向默认文件目录的符号链接（然后在 Pantheon 端链接到 /files）。请确保本地存在 /default/files 目录，以便文件有存放的地方。
4. 运行 git add files 并将符号链接提交到仓库。
将发布后脚本放在 Pantheon 可以读取的正确位置（在网站目录内）。
1. 创建 /web/private/scripts 目录。
2. 将 /scripts/pantheon/post_deploy.php 文件移动到 /web/private/scripts。
3. 删除空的 /scripts/pantheon 文件夹。
Settings.php修改
1. 将初始 Pantheon 安装中的 settings.pantheon.php 文件复制到您的 www（或相关站点目录）。
2. 打开 /web/sites/www/settings.php 并找到 "包含服务器特定配置" 部分。
3. 取消注释 Pantheon 部分。
4. 从其他提供商中删除不需要的服务器特定配置。

特定提供者修改：Platform.sh

删除Platform.sh中不必要的文件和目录
Settings.php修改
1. 将初始 Platform.sh 安装中的 settings.platformsh.php 文件复制到您的 www（或相关站点目录）。
2. 打开/docroot/sites/www/settings.php并找到“包含服务器特定配置”部分。
3. 取消注释 Platform.sh 部分。
4. 从其他提供商中删除不需要的服务器特定配置。

@TODO 平台.sh 中缺少一些文件和配置，但仍需要在 KIT 中包含。

重命名 docroot 为 web

一些提供者需要不同的 docroot 目录。

将 docroot 目录重命名为 web。
在以下文件中更新 docroot 引用为 web
- /.docksal/docksal.env
- /.gitignore
- /composer.json（之后需要运行 composer install 以重新生成 autoload.php 文件）
- /drush/* 文件（/drush/sites/www.site.yml 等）
- /patches/htaccess.patch
- /source/gulpfile.js
- /source/eslintrc.js

注意和建议

环境别名

www.domainname.com
dev-www.domainname.com
stg-www.domainname.com
prod-www.domainname.com (for pre-go-live)

我们发现，在生产 URL 中添加环境前缀是一个低投入、高回报的行动。这允许使用更容易记住和访问的环境 URL，无论是那些正在网站上工作的人还是客户。

主题开发

当使用 fin kit/theme 命令创建新主题时，您将为您创建两个目录结构

docroot/themes/custom/yourtheme - 这意味着它只包含 Drupal 需要渲染网站的文件 - 例如 css、javascript、图像、模板文件。它不包含生成这些文件的源文件（例如 sass 文件）。需要注意的是，此目录下的一些文件是生成的（见下一点），而一些（例如模板文件）则应直接编辑。
source/themes/custom/yourtheme - 包含生成 docroot/themes/custom/yourtheme 中文件的全部源文件。

Gulp 用于处理 source 中的文件，并将相应的输出写入 docroot 下相应的主题目录。默认 gulp 文件（source/gulpfile.js）已设置了一组大多数主题需要的任务。它还设置为在 source/themes/custom 下的所有目录中运行这些任务。这允许开发者开发多个主题（例如基本主题和子主题），并使用单个命令构建它们。

默认 gulp 文件提供以下功能

Sass - 处理每个主题目录下 styles 中的所有 scss 文件并生成源映射。输出放置在 docroot/themes/custom/yourtheme/css。
Javascript - 复制并为每个主题目录下 scripts 中的所有 js 文件生成源映射。输出放置在 docroot/custom/yourtheme/js。
图像 - 最小化 images 下的所有图像并将其输出放置在 docroot/custom/yourtheme/images。
字体 - 将 fonts 下的所有文件复制到 docroot/custom/yourtheme/fonts。
图标 - 编译 icons 下的所有 svg 文件并将输出写入 docroot/custom/yourtheme/styles/vendor 和 docroot/custom/yourtheme/fonts/icons 目录。
测试 - 根据配置在 source/.sass-lint.yml 和 source/.eslintrc 中的 sass 和 javascript 文件的 linting。

默认 gulp 文件提供的任务

默认 - 根据上述描述构建 Sass、JavaScript、图片、字体和图标。
测试 - 运行 Sass 和 JavaScript 代码检查器。
监视 - 当在源目录结构中文件发生变化时，构建默认任务中包含的所有内容。

vmlyr-drupal / kit

维护者

详细信息