企业官网建设流程全解析

BookStack 开发与测试指南：从本地环境搭建到代码规范与自动化测试

【免费下载链接】BookStackNOW MANAGED ON CODEBERG项目地址: https://gitcode.com/gh_mirrors/bo/BookStack

本指南以仓库 dev/docs/development.md 为核心，系统梳理 BookStack 的日常开发工作流：包括基于 npm 的前端资源构建（SASS + JavaScript）、覆盖全平台的 PHP 自动化测试、PHP/JavaScript 代码规范与静态分析工具，以及一套开箱即用的 Docker Compose 开发环境（含 MySQL、Node 资源监听与 MailHog 邮件捕获）。读完本文，你将能够独立搭建 BookStack 开发环境，理解其"development 分支开发 → release 分支构建发布"的协作模式，并掌握资源构建、测试编写与代码质量检查的完整实操方法。

分支与版本管理策略

所有 BookStack 开发工作都发生在development分支上。当到达发布节点时，development分支会被合并到release分支，同时完成 CSS 与 JS 的构建和压缩（minify），并以版本号打 tag。这意味着：

• 开发分支（development）：日常提交、功能迭代全部在此进行，构建产物不进入仓库维护范围；
• 发布分支（release）：存放构建、压缩后的资源产物，每个发布版本对应一个 tag。

当前开发环境的前端要求为Node.js v22.0+（对应 docker-compose.yml 中node:22-alpine镜像与 package.json 中的工具链版本）。

构建 CSS 与 JavaScript 资源

BookStack 使用SASS编写样式，CSS 与 JavaScript 都通过一系列 npm scripts 完成构建。核心构建脚本定义在 package.json 的scripts字段中，其底层分工为：

• build:css:*：调用sass ./resources/sass:./public/dist，将resources/sass下的样式编译输出到public/dist；
• build:js:*：调用node dev/build/esbuild.mjs，使用 esbuild 打包resources/js源码；
• build/production/dev：通过npm-run-all并行执行上述 CSS 与 JS 任务。

常用构建命令

# 安装 NPM 依赖（首次克隆仓库后必做） npm install # 以开发模式构建资源（含 sourcemaps） npm run build # 构建并压缩资源，用于生产发布 npm run production # 以开发模式构建（带 sourcemaps）并监听文件变化 npm run dev

其中npm run dev（等价于npm run watch）适合开发时持续使用：SASS 以--watch --embed-sources模式监听resources/sass，esbuild 以 watch 模式监听 JS 源码，任何改动都会立即重新编译。

构建产物统一输出到public/dist目录供浏览器加载。从源码结构看，BookStack 采用"服务端渲染为主、JavaScript 按需增强"的架构，具体的前端组件体系（$refs、$opts、$emit等）可参阅 dev/docs/javascript-code.md；用于扩展系统行为的公开事件 API 见 dev/docs/javascript-public-events.md。

自动化应用测试

BookStack 拥有庞大的 PHP 测试套件，覆盖应用各层功能，项目要求所有新增与变更都尽量配套测试。测试基于PHPUnit与 Laravel 的测试框架扩展构建，测试用例全部位于tests/目录。测试细节请参阅 dev/docs/php-testing.md。

测试数据库准备

应用测试以功能测试（functional）为主而非单元测试，会真实模拟用户操作与系统组件，因此依赖数据库。为避免污染开发数据库，测试使用独立的mysql_testing连接，其默认凭据为：

你需要在本地创建满足上述凭据的数据库；若不想使用默认值，可在.env或环境中定义TEST_DATABASE_URL：

TEST_DATABASE_URL="mysql://username:password@host-name:port/database-name"

首次运行前需迁移并填充测试数据，一条命令即可完成：

composer refresh-test-database

该命令在 composer.json 中定义为：设置APP_TIMEZONE=UTC后依次执行php artisan migrate:refresh --database=mysql_testing与php artisan db:seed --class=DummyContentSeeder --database=mysql_testing。测试环境的全部环境变量可在 phpunit.xml 中查看（如APP_ENV=testing、DB_CONNECTION=mysql_testing、CACHE_DRIVER=array等）。

运行测试

在应用根目录执行：

composer test

或直接调用 PHPUnit：

php vendor/bin/phpunit

PHPStorm 等编辑器内置了对单文件、目录或类的测试支持；命令行下也可以精确指定测试范围：

# 运行 ./tests/HomepageTest.php 文件中的全部测试 php vendor/bin/phpunit ./tests/HomepageTest.php # 运行 ./tests/User 目录下的全部测试 php vendor/bin/phpunit ./tests/User # 按测试方法名过滤 php vendor/bin/phpunit --filter test_default_homepage_visible # 按测试类名过滤 php vendor/bin/phpunit --filter HomepageTest

如需验证代码对 PHP 弃用特性（deprecations）的兼容性，可取消TestCase@setUp中相关行的注释后运行；这通常用于依赖升级、PHP 大版本升级等维护任务，一般 PR 无需执行。

编写测试的约定

编写测试前建议先通读与你需求相近的既有用例。测试代码风格可以比核心业务代码更"随意"，项目明确认为"粗糙的测试也胜过没有测试"。基本约定如下：

• 测试类必须位于tests/目录、以Test结尾，并继承Tests\TestCase；
• 测试方法使用 snake_case 命名，以test_开头，且必须为 public 方法；
• 所有外部远程资源（HTTP 调用、LDAP 连接等）都必须 mock；
• 断言中优先硬编码期望文本与 URL，以更灵敏地捕获系统变化；
• 除非必要，避免使用 admin 用户测试，改用低权限用户以确保权限系统在测试中被实际执行；
• 测试"某内容不存在"（如assertDontSee('TextAfterChange')）时，必须同时提供正向确认（如assertSee('TextBeforeChange')）。

常用测试助手

默认TestCase内置了大量测试助手，常用示例如下：

// 以指定权限级别的登录用户运行测试 $this->asAdmin(); $this->asEditor(); $this->asViewer(); // 提供书架/书/章节/页面等实体内容与操作 $this->entities; // 提供各类用户与角色能力 $this->users; // 提供系统与内容权限相关操作 $this->permissions; // 提供文件与上传相关方法 $this->files; // 将响应解析为 HTML 并断言结构（基于 asserthtml 库） $this->withHtml($resp); // 示例： $this->withHtml($this->get('/'))->assertElementContains('p[id="top"]', 'Hello!');

代码规范与静态分析

项目使用多款工具管理代码质量与格式。提交 PR 时按项目规范格式化有助于清晰审阅，不过无需过度担心——自动化工具会在后续流程中兜底处理。

PHP：PHP_CodeSniffer + PHPStan（Larastan）

PHP 代码规范由 PHP_CodeSniffer 管理，静态分析由 PHPStan 及其 Laravel 适配层 Larastan 承担（版本约束见 composer.json 的require-dev，如larastan/larastan: ^v3.0、squizlabs/php_codesniffer: ^4.0.1）：

# 使用 PHP_CodeSniffer 执行代码 lint composer lint # 同上，但在输出中显示规则名 composer lint -- -s # 通过 phpcbf 自动修复格式与 lint 问题 composer format # 通过 larastan/phpstan 执行静态分析 composer check-static

这些命令对应 composer.json 中的lint（phpcs）、format（phpcbf）与check-static（phpstan --memory-limit=2g）脚本；PHPStan 配置见 phpstan.neon.dist，代码规范规则见 phpcs.xml。

JavaScript：ESLint

JavaScript 规范由 ESLint 管理，规则配置维护在 package.json（新版已拆分出独立的 eslint.config.mjs 配置文件），扫描范围覆盖resources下的.js与.mjs文件：

# 使用 ESLint 执行代码 lint npm run lint # 尽可能自动修复问题 npm run fix

使用 Docker 进行开发

仓库自带的 Docker Compose 配置专为开发目的设计（见 docker-compose.yml），它会构建一个装有全部所需 PHP 扩展的镜像、启动 MySQL 服务，以及一个持续监听 UI 资源的 Node 容器。

环境要求

• 已安装 Docker 与 Docker Compose；
• 当前用户属于docker组。

快速开始步骤

1. 复制.env.example为.env：将APP_KEY改为随机 32 位字符串，并设置APP_ENV=local；
2. 确保 8080 端口空闲，否则将DEV_PORT改为宿主机上的空闲端口；
3. 执行chgrp -R docker storage：开发容器会把storage、public/uploads、bootstrap/cache目录的属主改为容器内的www-data用户，以便 BookStack 写入；你需要先将storage目录的组改为宿主机docker组，避免失去访问权限；
4. 运行docker-compose up，等待镜像构建完成并执行完所有数据库迁移；
5. 在localhost:8080（或你指定的端口）使用admin@admin.com/password登录。

启动过程中，容器入口脚本 dev/docker/entrypoint.app.sh 会自动执行composer install、等待db:3306就绪、运行php artisan migrate --database=mysql --force并修正目录权限，随后启动 Apache（文档根目录为/app/public）。Node 容器入口 dev/docker/entrypoint.node.sh 则执行npm install后运行npm run watch持续监听资源变化。

在容器内执行 Artisan 命令

docker-compose run app php artisan list

邮件捕获：MailHog

Docker 环境内置了一个 MailHog 实例，并通过环境变量将 BookStack 发出的所有邮件重定向到 MailHog，可在localhost:8025的 Web 界面查看。如需更换端口，设置DEV_MAIL_PORT环境变量即可（对应 docker-compose.yml 中${DEV_MAIL_PORT:-8025}:8025的端口映射）。

在 Docker 中运行测试

启动常规开发 Docker 后，先迁移并填充测试数据库（只需执行一次）：

docker-compose run app php artisan migrate --database=mysql_testing docker-compose run app php artisan db:seed --class=DummyContentSeeder --database=mysql_testing

迁移与填充完成后，即可运行测试套件：

docker-compose run app php vendor/bin/phpunit

调试：Xdebug

Docker 环境自带 Xdebug，可在9090 端口监听调试连接。Xdebug 配置见 dev/docker/php/conf.d/xdebug.ini：启用debug模式、start_with_request=yes，客户端主机指向host.docker.internal（该主机映射由 docker-compose.yml 的extra_hosts: host.docker.internal:host-gateway提供），端口为 9090。对于 VS Code 等编辑器，可能需要将工作区文件夹映射到容器内的/app目录才能正常工作。

小结

• 开发统一在development分支进行，发布时合并到release并压缩构建资源；
• 前端资源构建由 SASS + esbuild 驱动，npm run dev提供带 sourcemap 的热更新监听；
• 测试以功能测试为主，使用独立mysql_testing数据库，composer refresh-test-database一键准备测试数据；
• 代码质量由 PHP_CodeSniffer、PHPStan/Larastan 与 ESLint 三层把关，均有对应 composer/npm 脚本；
• Docker Compose 环境（PHP 8.3 + MySQL 8.4 + Node 22 + MailHog + Xdebug）可让新开发者几分钟内进入完整可调试的开发状态。

如需深入探索，可继续阅读 dev/docs/php-testing.md、dev/docs/javascript-code.md 与 dev/docs/development.md 引出的其他开发文档（如 JavaScript 公开事件、WYSIWYG 编辑器 API 等），并结合仓库源码与tests/目录中的既有用例进行实践。

【免费下载链接】BookStackNOW MANAGED ON CODEBERG项目地址: https://gitcode.com/gh_mirrors/bo/BookStack