CatchAdmin 专业版安装指南

INFO

本章节介绍 CatchAdmin 专业版本地开发环境的安装配置。生产环境部署请查看部署章节

环境要求

#	环境	版本
1	PHP	>= 8.2+
2	Nginx	latest
3	Mysql	>= 5.7
4	Node	>= 22

WARNING

CatchAdmin 专业版 3.x 版本需要 Node.js 20，4.0+ 版本需要 Node.js 22。请根据项目版本选择对应的 Node.js 运行环境。

开发工具准备

在安装 CatchAdmin 专业版项目之前，您需要准备以下必要的开发工具和运行环境：

#	必须	官网
1	Composer PHP 依赖管理器	https://getcomposer.org/download/
2	Node.js (>= 22)	https://nodejs.org/zh-cn/
3	Yarn 前端包管理器	https://yarn.bootcss.com/
4	Vite 前端构建工具	https://cn.vitejs.dev/

WARNING

请确保上述开发工具已正确安装并可在命令行中使用，否则 CatchAdmin 专业版项目安装将会失败。

下载代码

购买 CatchAdmin 专业版授权后，可以从授权仓库下载项目源码 在授权仓库进行下载。这里分四种方式，分别解释下。

• 版本: 阶段性稳定功能的版本，可以在更新里面看到 版本更新日志
• 分支: 分支功能都是优先于版本的，都是直接提交的，你可以当作开发分支来看，不保证稳定性。
• commit: commit 用于修复一些紧急 bug，你可以看作一个一个的即时的小补丁
• 补丁：版本之间的 diff 差异，例如你目前正在使用 v3.5.0，需要升级到 v4.0.0，就需要下载 v4.0.0 的补丁。查看如何更新补丁。需要注意的是补丁不会跨版本。

请根据实际需求选择合适的版本下载源码包，所有代码包均为 zip 压缩格式，下载解压后即可进行 CatchAdmin 专业版项目的安装配置。

进行开发时建议阅读最佳开发实践，了解项目结构和版本升级流程

CatchAdmin 专业版项目安装

WARNING

请确保已完成开发工具准备中的所有环境配置，缺少必要工具将导致 CatchAdmin 专业版安装失败。

命令行认证

INFO

推荐使用该方式安装

CatchAdmin 专业版提供便捷的授权认证脚本，自动完成用户验证和项目依赖安装。进入项目根目录，执行以下认证命令

首先获取授权码，在授权码页面获取，点击生成授权码之后。记得保存，页面不做二次展示

进入到源码解压之后的根目录，然后使用下面的命令

php auth 邮箱 这里替换成生成的授权码

# 假设你的邮箱是 catch@pro.com，授权码是 123456 , 那么需要执行如下的命令
php auth catch@pro.com 123456

WARNING

系统会对每个账户下载来源统计，所以请不要泄露账户。如果出现不寻常的情况，我们会对账户进行一些限制。如果有误，烦请联系管理员

系统将自动通过 Composer 安装 PHP 项目依赖包。依赖安装完成后，需要初始化 CatchAdmin 专业版项目配置和数据库结构，执行以下命令

# 安装后台, 按照提示输入对应信息即可
php artisan catch:install

更多其他的 CatchAdmin 开发相关的内置命令

TIP

生产环境部署时，请使用 php artisan catch:install --prod 命令进行项目初始化配置。

Vue 前端项目配置

INFO

以下 Vue 前端项目配置步骤通常由 catch:install 命令自动完成。如需手动配置，请按照下面的步骤执行。

Vue 前端项目源码位于 CatchAdmin 专业版根目录下的 web 目录中

cd web

# 配置 npm 镜像源（提升下载速度，如使用代理可忽略）
yarn config set registry https://registry.npmmirror.com

# 安装 Vue 项目 npm 依赖包
yarn install

进入 web 目录，创建 Vue 项目的环境配置文件 .env，配置内容如下

TIP

catch:install 命令已自动生成此配置文件，如需自定义 API 地址或项目名称，可按以下格式修改。

# 记住一定要加上 api/ 前缀
VITE_BASE_URL=http://127.0.0.1:8000/api/

# 项目名称
VITE_APP_NAME=xxx项目

启动命令

使用以下命令启动 Vue 前端项目的 Vite 开发服务器

yarn dev

WARNING

CatchAdmin 专业版采用前后端分离架构，不能直接访问 PHP 后端项目（会产生异常）。需要启动 Vue 前端项目通过 API 接口与后端通信。

初次使用 Vue 开发者建议阅读 Vue.js 官方文档。CatchAdmin 专业版前端 UI 组件基于 Element Plus 构建。

开发环境启动

CatchAdmin 专业版 4.0.0+ 版本提供了一键启动开发环境的便捷命令，无需分别执行 php artisan serve 和 yarn dev

composer run dev

WARNING

如果本地开发环境已配置了集成环境（如 XAMPP、WAMP Laragon 等）或使用 Nginx/Apache 等 Web 服务器，请不要使用 composer run dev 命令。

此种情况下请单独启动前端项目：进入 web 目录后执行 yarn dev

如何实现

以下为技术实现说明，便于故障排查：

• 此命令启动的 PHP 内置服务器默认监听 8000 端口，如需修改请编辑 composer.json 中的启动脚本

• 依赖 concurrently 包实现并发启动，通常已预装。如缺失可全局安装：npm install -g concurrently

最佳开发实践

开发实践, 如何升级

补丁安装

请从授权仓库下载对应版本的升级补丁包 下载补丁包后，将其放置到 CatchAdmin 专业版项目根目录。假设补丁文件名为 xxxxx.zip，使用以下命令执行版本升级

php artisan catch:upgrade xxxx.zip