EspoCRM 安装部署避坑上手：从环境检查到上线只需四步-平芜编程栈

EspoCRM 安装部署避坑上手：从环境检查到上线只需四步

【免费下载链接】espocrmEspoCRM – Open Source CRM Application项目地址: https://gitcode.com/GitHub_Trending/es/espocrm

EspoCRM 是一款开源 CRM 系统，用 PHP 编写，前端是单页应用，后端对外提供 REST API。它把客户联系、销售机会、营销活动、客服工单放进同一个后台管理，适合不想被 SaaS 订阅费绑定、又希望数据留在自己服务器上的团队。在一台干净的机器上，从拉代码到建好管理员账号，通常半小时左右就能走完，剩下的时间主要花在权限和 Web 服务器的细节上。

先把 PHP、数据库和目录权限这三关过掉

部署前最值得花时间的不是装软件，而是确认三样东西。

第一，PHP。版本要求是 8.3 到 8.5（8.6 以下），低于 8.3 装不动，高于 8.5 可能跑起来报错。扩展方面，pdo、gd、zip、intl、mbstring、openssl、json、xml、curl这几项缺一个都会在安装向导的环境检查里被打回，exif、dom、ctype也建议一并装上。用php -v看版本、php -m列扩展，缺什么补什么。

第二，数据库。MySQL 8.0 及以上、MariaDB 10.3 及以上都可以，PostgreSQL 15 也能用。准备一个有建库建表权限的账号，连接地址先在本机localhost上测通再说。

第三，资源与权限。内存 512MB 能跑，生产环境建议 1GB 以上；磁盘预留 1GB。目录权限有讲究：data/和custom/必须对 Web 进程可写，否则安装向导走到一半会卡住，常见处理是chmod -R 775 data/ custom/。

拉取源码并核对文件是否完整

获取代码用下面这条命令即可：

git clone https://gitcode.com/GitHub_Trending/es/espocrm cd espocrm

如果拿的是压缩包，解压到 Web 根目录同样的效果。拉完先确认目录结构正常：application/是全部后端代码，client/是前端静态资源，data/放运行时配置和日志，custom/是留给二次开发的目录，public/index.php是站点入口。确认data/和custom/可写、整体目录属主是 Web 运行用户，这一步做对了，后面九成的 500 错误都不会出现。

给 Web 服务器加两条重写规则

EspoCRM 的所有页面都走index.php统一入口，所以重写规则是必选项，不是可选项。

Apache 用户先确认mod_rewrite已启用，然后在虚拟主机里对站点目录放开AllowOverride All，让随代码提供的.htaccess生效。Nginx 用户没有.htaccess，得自己写两条：try_files $uri $uri/ /index.php?$query_string;处理页面路由，再加一行client_max_body_size 50M;给附件上传留余量。改完务必重启服务再验证，否则你以为在测新配置，其实还在跑旧规则。

打开浏览器走安装向导，五步建库建账号

在浏览器访问你的域名，未安装时会自动跳到安装向导，流程大致是：环境检查 → 填数据库连接 → 填站点偏好 → 建管理员账号 → 完成初始化。

数据库一步填主机、端口、库名、用户名、密码，向导会实际连一次并建表，连不通会当场给出原因，不用装完再猜。管理员账号建议在这一步就起一个强密码，装完再改要多走一轮流程。看到完成页并成功登录后台，安装就算结束；此时data/config.php已生成数据库连接等核心配置，之后改配置都从它入手。

装不动的时候，按现象对号入座

安装页空白或直接 500：先查 PHP 错误日志（通常在data/logs/或系统日志目录），九成是扩展缺失或data/、custom/不可写；补扩展、修属主和权限后重试。
数据库连接失败：在命令行用同一账号手动连一次，排除网络、白名单、密码问题；再确认该账号有建库建表权限。
URL 里带着 index.php、刷新就 404：重写没生效。Apache 查mod_rewrite和AllowOverride，Nginx 查try_files，改完记得重启服务。
附件传不上去：改php.ini里的upload_max_filesize和post_max_size（例如各 20M），顺带把memory_limit调到 256M 以上，然后重启 PHP 服务。