1. 为什么值得折腾禅道的本地开发环境很多人第一次接触禅道二次开发都是被一个很具体的需求逼出来的公司用禅道做项目管理和缺陷跟踪但流程里总有几个环节跟实际业务对不上比如想让钉钉审批通过后自动在禅道里建单或者想在提Bug时自动带出某个产品线的默认模块。市面上的插件要么不贴合要么收费还不给源码最后只能自己上手改。禅道本身是开源项目PHP技术栈代码结构相对清晰二次开发的门槛并不算高。但真正动手之前第一道坎往往不是写代码而是把本地环境跑起来并且能断点调试。我见过太多人卡在这一步代码下载了数据库导入了页面能打开但一改代码就报错或者改了没反应最后只能靠echo和die这种原始手段排查效率极低。这篇文章要解决的就是这个问题。我会从零开始把禅道本地开发与调试环境的搭建过程完整走一遍包括技术选型、版本匹配、目录结构、调试配置、常见坑点。适合两类人一是刚接手禅道二开任务、还没搭好环境的开发者二是环境能跑但调试体验很差、想升级工作流的同行。整个过程我会解释每一步为什么这么做而不是只给命令让你照抄。需要提前说明的是禅道有多个版本分支开源版、企业版、旗舰版在代码结构上有差异二次开发的自由度也不同。本文以开源版为主线因为它的代码完全开放最适合学习和深度定制。企业版和旗舰版的二开通常需要走官方扩展机制思路类似但细节不同我会在相关位置点出来。2. 环境搭建前的技术选型与版本对齐2.1 PHP版本的选择逻辑禅道的不同大版本对PHP版本要求不一样。早期版本如9.x、10.x跑在PHP 5.6到7.2之间而较新的版本如18.x、20.x已经支持PHP 7.4甚至8.0。选错版本最典型的症状是页面能打开但某些功能报致命错误或者中文乱码、时区异常。我的建议是以你生产环境正在运行的禅道版本为准本地环境尽量对齐。原因很简单二次开发的代码最终要部署到生产环境如果本地用PHP 8.0开发生产还是PHP 7.2那么你用的某些语法特性比如构造器属性提升、联合类型在生产上直接报语法错误这种问题在部署时才暴露排查成本很高。具体操作上先确认生产禅道的版本号后台管理页面底部或config目录下的版本文件然后查官方文档对应的PHP要求。如果生产是禅道18.x通常PHP 7.4是比较稳妥的选择兼容性好扩展生态也成熟。2.2 Web服务器与数据库的搭配禅道官方推荐用Apache MySQL的组合Nginx也能跑但需要额外配置重写规则。对于本地开发我倾向于用集成环境来快速起步比如phpStudy、XAMPP这类它们把Apache/Nginx、PHP、MySQL打包好了省去单独配置的时间。但集成环境有个隐患它自带的PHP可能缺少禅道需要的扩展。禅道依赖的PHP扩展主要包括pdo_mysql、mbstring、gd、curl、json、zip等。其中gd库用于图表和验证码zip用于导出功能缺了会在特定操作时报错。搭建完成后用phpinfo()或者命令行php -m检查一遍扩展列表缺什么补什么。数据库方面MySQL 5.7和8.0都可以但要注意8.0默认的认证插件是caching_sha2_password老版本的PHP MySQL驱动可能连不上。如果遇到连接报错把用户认证方式改成mysql_native_password即可。字符集统一用utf8mb4避免emoji和特殊字符存储出问题。2.3 代码获取与目录规划禅道开源版的代码可以从官方渠道下载完整安装包也可以从代码托管平台获取。安装包里包含了wwwWeb根目录、config、db、module、lib等核心目录。二次开发主要关注这几个位置目录作用二开关注度module各功能模块的业务逻辑高改流程主要在这里lib公共类库和框架代码中理解框架机制时看config配置文件高数据库、路由等配置www入口文件和静态资源中加自定义页面时用db数据库脚本低除非改表结构extension扩展目录高官方推荐的二开入口我习惯把代码放在一个独立的开发目录比如/data/dev/zentao然后通过Web服务器的虚拟主机指向www目录。这样做的目的是把代码和环境分离方便用Git做版本管理也方便切换不同版本做对比。提示不要直接在解压后的安装包里改代码先复制一份出来作为开发副本。原始包保留着改坏了可以随时对照。3. 数据库导入与站点初始化的关键细节3.1 数据库导入的两种路径禅道的数据库初始化有两种方式一种是通过Web安装向导一步步走另一种是直接导入SQL文件。对于二次开发我更推荐Web安装向导因为它会自动处理表前缀、初始数据、管理员账号等省去手动改SQL的麻烦。安装向导的流程大致是访问站点首页选择语言和数据库类型填写数据库连接信息设置管理员账号然后等待安装完成。这里有几个容易出问题的地方第一数据库用户权限。不要用root跑应用新建一个专用用户授予该数据库的全部权限即可。命令大概是CREATE DATABASE zentao_dev DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER zentao_devlocalhost IDENTIFIED BY your_password; GRANT ALL PRIVILEGES ON zentao_dev.* TO zentao_devlocalhost; FLUSH PRIVILEGES;第二安装过程中如果卡在某个步骤不动多半是PHP执行超时或内存不足。临时把max_execution_time调到300memory_limit调到256M以上装完再改回来。第三安装完成后禅道会在config目录下生成my.php文件里面保存了数据库连接信息。这个文件是本地环境特有的不要提交到代码仓库应该加入.gitignore。3.2 站点访问与伪静态配置安装完成后访问站点应该能看到登录页。如果出现404或者样式丢失通常是Web服务器的重写规则没配好。禅道用的是PATH_INFO模式的路由Apache下需要开启mod_rewrite并在虚拟主机里允许.htaccess生效Nginx下需要加一段try_files配置。Apache的虚拟主机配置示例VirtualHost *:80 ServerName zentao.local DocumentRoot /data/dev/zentao/www Directory /data/dev/zentao/www Options Indexes FollowSymLinks AllowOverride All Require all granted /Directory /VirtualHostNginx的对应配置server { listen 80; server_name zentao.local; root /data/dev/zentao/www; index index.php index.html; location / { try_files $uri $uri/ /index.php?$args; } location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } }配好之后在本地hosts文件里加一行127.0.0.1 zentao.local用域名访问比用localhost/zentao/www这种路径访问更接近生产环境也能避免一些相对路径引发的问题。3.3 初始配置的几项调整装好之后进后台做几项对开发有帮助的调整。第一打开调试模式。禅道在config/my.php里可以设置$config-debug true;开启后错误信息会直接显示在页面上而不是只写日志。第二调整日志级别把SQL日志打开方便排查数据问题。第三关闭生产环境才需要的缓存和压缩避免改了代码看不到效果。这些调整的本质是让环境更透明开发阶段最怕的就是问题被藏起来。生产环境追求稳定和性能开发环境追求可见和可调试两者的配置取向是相反的。4. 调试工具链的配置与断点调试实战4.1 Xdebug的安装与PHPStorm联动靠var_dump和die调试禅道这种规模的代码效率太低。真正提升开发体验的关键一步是配好Xdebug IDE的断点调试。Xdebug是PHP的调试扩展配合PHPStorm或VSCode可以实现单步执行、变量查看、调用栈追踪。安装Xdebug的步骤先确认PHP版本和是否线程安全TS/NTS然后去Xdebug官网下载对应版本的扩展文件放到PHP的ext目录在php.ini里加载zend_extensionxdebug.so xdebug.modedebug xdebug.client_host127.0.0.1 xdebug.client_port9003 xdebug.start_with_requestyes xdebug.idekeyPHPSTORMWindows下扩展文件是php_xdebug.dll配置项类似。xdebug.mode在Xdebug 3.x里取代了原来的remote_enable等一堆开关设成debug就够用了。PHPStorm这边进入Settings PHP Debug确认Debug port是9003然后配置一个Servers把zentao.local映射到本地代码目录。最后点工具栏的Start Listening for PHP Debug Connections在浏览器里访问禅道页面PHPStorm就会在断点处停下来。4.2 断点调试在禅道二开中的实际用法配好之后调试禅道代码就变得很直观了。举个例子你想搞清楚提Bug这个动作到底走了哪些代码就在module/bug/control.php的create方法里打个断点然后在页面上提交一个BugPHPStorm会停在断点处你可以看到请求参数、当前变量、调用栈。调用栈特别有用。禅道的框架是MVC结构一个请求从入口文件www/index.php开始经过路由解析、模块加载、方法调用最后渲染视图。通过调用栈你能清楚地看到框架是怎么把URL映射到具体方法的这对理解禅道的运行机制帮助极大。我个人的经验是先通过断点把核心流程走一遍再动手改代码。很多人上来就改改完不知道哪里出了问题就是因为对原有流程没有建立清晰的认知。断点调试是建立这种认知最快的方式。4.3 日志与SQL追踪的辅助手段断点调试适合精确定位但有些场景下不方便打断点比如定时任务、异步请求、批量操作。这时候日志就是主要手段。禅道自带日志机制在config/my.php里可以配置日志路径和级别。把SQL日志打开后每个请求执行的SQL都会记录下来排查数据问题时非常有用。另外浏览器端的网络面板也别忽略。禅道的很多操作是AJAX请求通过面板能看到请求的URL、参数、响应配合服务端日志基本能覆盖大部分排查场景。注意调试配置只用于本地环境绝对不要带到生产环境。Xdebug开启后性能下降明显日志全开也会快速占满磁盘。5. 二次开发入口的选择与代码组织5.1 官方扩展机制与直接改源码的取舍禅道提供了扩展机制在extension目录下可以按模块放置自定义代码框架会优先加载扩展目录里的文件。这种方式的优点是升级禅道时不会覆盖你的改动缺点是有些深层逻辑改起来不够灵活。直接改源码则相反改起来自由但升级时要做代码合并容易冲突。我的建议是能走扩展就走扩展扩展满足不了再改源码。具体判断标准如果只是加字段、改页面、加接口扩展基本够用如果要改核心流程、改框架行为那只能动源码。无论哪种方式都要用Git管理起来。每次改动前先提交一个基线版本改完再提交这样出问题可以随时回滚也能清楚地看到自己改了什么。5.2 模块目录结构与命名规范禅道的模块目录结构很规整每个功能模块一个目录里面通常包含control.php控制器处理请求和业务逻辑model.php模型处理数据操作view/视图模板lang/语言文件config.php模块配置二次开发时新增功能一般遵循同样的结构。比如你要加一个项目周报功能就在module下建一个weeklyreport目录按同样的模式组织代码。命名上保持和现有模块一致的风格全小写、无下划线这样框架的路由才能正确解析。5.3 数据库操作的注意事项禅道封装了自己的数据库操作层不建议直接写原生SQL。框架提供了$this-dao对象支持链式调用查询、插入、更新。用框架的DAO层有几个好处自动处理表前缀、自动转义、支持分页和调试输出。如果确实需要写复杂SQL也要通过$this-dao-query()执行而不是直接用mysql_query。另外改表结构时要同步更新db目录下的安装脚本否则新环境部署时会缺字段。这一点在团队协作中特别重要我见过因为忘了更新安装脚本导致测试环境部署失败的案例。6. 环境搭建中那些容易踩的坑6.1 权限问题导致的诡异报错禅道运行过程中会往www/data、tmp、logs等目录写文件。如果这些目录没有写权限会出现各种奇怪的报错比如上传附件失败、缓存无法生成、日志写不进去。Linux下用chmod -R 755或chown把属主改成Web服务器用户即可。这个坑的隐蔽性在于报错信息往往不直接指向权限而是提示文件不存在或操作失败让人往错误的方向排查。我的习惯是搭好环境后先检查一遍所有需要写入的目录权限省得后面被坑。6.2 时区和字符集的隐性影响PHP的时区设置和MySQL的时区设置如果不一致会导致时间显示错乱。比如PHP设了Asia/ShanghaiMySQL还是UTC那么存进去的时间和读出来的时间差8小时。在php.ini里设date.timezone Asia/ShanghaiMySQL的my.cnf里设default-time-zone 08:00两边对齐。字符集问题类似。数据库、表、连接三层的字符集要统一成utf8mb4。连接层可以在config/my.php的数据库配置里指定或者执行SET NAMES utf8mb4。字符集不统一最典型的表现是中文乱码而且往往是存进去正常、读出来乱码或者反过来排查起来很费劲。6.3 缓存导致的改了没反应禅道有缓存机制模板编译、配置、语言文件都可能被缓存。改了代码或配置后如果没生效先清缓存。缓存目录通常在tmp下直接删掉里面的内容即可。开发阶段可以在配置里关闭缓存避免频繁手动清理。这个坑几乎每个新手都会踩。明明改了代码刷新页面还是老样子以为是代码没保存或者改错了地方折腾半天才发现是缓存。养成改完先清缓存的习惯能省下大量时间。6.4 版本升级后的代码冲突如果你改过源码禅道升级时会遇到代码冲突。升级包里的文件和你的修改版本不一致需要手动合并。这是直接改源码的代价。降低这个代价的办法是改动尽量集中、加注释标记、用Git记录每次改动的原因。升级时先对比差异再决定保留哪些改动。扩展机制在这方面优势明显升级时基本不用管。所以再次强调能用扩展就用扩展。7. 把环境变成可持续的开发工作流环境搭起来只是第一步真正影响效率的是日常开发的工作流。我自己的做法是代码用Git管理分支上开发新功能主分支保持和官方版本同步调试配置写成文档换机器时照着配一遍常用操作清缓存、导数据、跑测试写成脚本一条命令搞定。还有一点很重要保持本地环境和生产环境的一致性。PHP版本、MySQL版本、关键扩展、配置项尽量对齐。本地跑得好好的上线出问题十有八九是环境差异导致的。如果生产环境不能随便动那就在本地尽量模拟比如用Docker把生产环境的配置固化下来。Docker方案值得单独提一句。用Docker Compose把PHP、MySQL、Nginx打包成一套新机器上docker-compose up就能拉起完整环境团队成员之间环境完全一致省去了我这里能跑你那里不能跑的扯皮。代价是初期配置要花点时间但对于长期做二开的团队来说这笔投入很划算。我在实际项目中的体会是环境搭建这件事第一次做会觉得繁琐但把每个环节的原理搞清楚之后后面换版本、换机器、带新人都会轻松很多。最怕的是照着教程抄一遍跑起来了但不知道为什么一旦出问题就束手无策。所以这篇文章我尽量把为什么讲清楚希望你在动手的时候不只是复制命令而是理解每一步背后的逻辑。后续如果要做具体的功能二开比如对接审批流、自定义报表、改造提Bug流程这套环境就是你的基础工作台。