简介DeWeb 是一套帮助 Delphi 开发者将传统桌面程序快速转换为网页应用的框架资源包定位清晰面向希望继续使用 Delphi 完成 Web 端开发的程序员无需学习 HTML、JavaScript、Java、PHP、ASP、C# 等语言即可生成支持手机、平板等多客户端访问的页面。压缩包共 2669 个文件整体约 24.59MB典型文件包括 pas 源码、dfm 窗体、dproj/dpk 工程与包文件、dcu 编译单元、js/css/html 前端资源、res/dcr 资源及 bat 构建脚本分别对应核心逻辑、界面布局、项目配置、预编译产物与自动化操作目录结构清晰便于按需查阅。资源附带 Delphi 10.1/10.2/10.3 版本的 dcu 文件、IcsV858 控件安装步骤、DelphiWeb 演示工程及新建页面的完整注册流程开发者可结合 main.pas 中的 RegisterClass/UnRegisterClass 用法快速上手。目前已有 1071 人学习下载尤其适合需要以 Delphi 统一前后端、快速交付响应式 Web 应用的团队或个人参考与二次开发。 前几天整理网盘备份在“存档不删”目录里翻出一个压了好几年的压缩包文件名是deweb2020-05-23 beta2 new2.rar。解压之前我还愣了一下等看到里面的文件结构才想起来这是当年自己做的一套轻量型网站快速发布工具前前后后迭代了三个多月最后停在 beta2 这个版本上。这东西算不上什么大项目但确实解决过一批人的实际问题不想碰服务器命令不想碰数据库只想把几个网页扔上线。我把它打成包发给过几个朋友后来因为忙着别的事就搁置了压缩包也就一直躺在网盘里。现在重新翻出来看里面的代码、注释、打包脚本和那份“发布前检查清单”反而比当时写的时候更有嚼头。这篇就借着这个压缩包把我当时的设计思路、技术选型、版本迭代过程和踩过的坑完整梳理一遍。1. deweb beta2 到底是什么一个“网页快速发布工具”的自白先说清楚这个东西的定位。deweb 的全称是 “Deliverable Web”我当时的想法很简单做一个让普通用户也能在十分钟内把一套静态网页发布到服务器上的小工具。它不是一个 CMS内容管理系统没有后台管理界面也没有数据库依赖核心就三个能力接收一个文件夹内含 HTML、CSS、JS、图片等静态资源自动分析文件结构生成一套可直接运行的站点配置通过 FTP 或本地目录方式发布到目标位置附带一个简单的在线预览页为什么做这个因为我当时遇到一个高频需求周围不少朋友在做个人作品集、小型活动页面、临时宣传页内容就是几个静态页面不需要动态功能。但他们卡在两步上一是本地做好网页后不知道怎么上传二是上传后访问不了要么是目录路径不对要么是文件权限有问题。市面上的工具分两种一种是前端构建工具Webpack、Gulp 这类定位是开发期用一般用户玩不转另一种是一键建站平台又太重动不动让你选模板、绑域名反而把简单的事搞复杂。我想要的中间地带是你给我一个文件夹我给你一个能跑的网站。deweb 就是往这个方向做的。beta2 是 2020 年 5 月 23 日定型的测试版本。文件命名里的new2是因为同一天我打包了三次前两次不是漏了文件就是版本号没更新第三次才确认无误。这个细节后面会展开讲打包这件事儿真不光是点一下“压缩”那么简单。2. 核心功能拆解模板导入、动态配置与本地预览2.1 文件结构解析不写代码的“配置即服务”deweb 最核心的逻辑是对用户传入的文件夹做静态分析。我当时用 PHP 写了一个入口脚本index.php它做以下几件事扫描目录中的所有文件按扩展名分组。HTML 归为页面文件CSS/JS归为资源文件图片归为媒体文件其他归为附件。读取每个 HTML 文件的第一行title标签自动把它作为页面名称。如果检测到nginx.conf.example或.htaccess.example自动生成对应的转发规则。这套逻辑把“手动配置服务器”压缩成了“扫描 自动生成”。用户不需要知道 404 页面怎么配、伪静态规则怎么写工具会基于已有的文件结构推断出来。比如当你有一个blog/index.html时工具会默认生成一条/blog到/blog/index.html的裸域名访问规则。2.2 发布流程的三段式设计整个发布流程我用了一张流程图来设计文字说明版本第一步选择本地目录就是你的网站文件夹第二步配置发布目标FTP 服务器信息或本地目录路径第三步预览 确认工具先自动生成一份预览页确认无误后执行发布第三步里的预览页是我觉得比较有价值的设计。在真正上传之前deweb 会生成一个.deweb_preview.html把这个站点的所有页面、资源文件、附件列成一张表格显示文件大小、文件类型、预计上传时间。这样做的好处是避免一种常见翻车传上去之后发现漏了这个 JS、少了个 CSS网站样式全崩了。表格里还有一个“循环依赖检查”的选项用来检测 HTML 中互相引用的资源是否都存在。因为是纯静态站点循环依赖出现的概率不高但我在测试时遇到过link relstylesheet hrefstyle.css写成了href./css/style.css但实际文件在css/style.css这种路径拼写错误。这个检查能提前把你从“传上去之后啥也不显示”的尴尬里救回来。2.3 本地预览服务器一个小但关键的细节直接双击 HTML 文件也能预览但浏览器会限制部分能力比如 fetch 本地文件。deweb 内置了一个极简的 PHP 开发服务器启动命令php -S 127.0.0.1:8080 -t ./这条命令会把当前目录作为站点根目录启动本地服务。基于这个原因deweb 的运行环境要求是 PHP 5.6 以上因为php -S是 PHP 5.4 引入的这个门槛在 2020 年完全不是问题。选择 PHP 而不是 Node.js 的原因很朴素那时候我的目标是让用户在自己电脑上就能跑起来Windows 用户装了 PHP 的比装了 Node 的多得多而且 PHP 自带 HTTP 服务省去 npm install 的依赖折腾。3. 从 beta2 new2 这个命名看版本管理的门道deweb2020-05-23 beta2 new2.rar这串名字看着随意其实信息量不小。它包含三个关键字段日期2020-05-23、版本beta2、修订序号new2。这正好对应了轻量工具开发中常用的“三段式存档法”。当时这么命名是因为有两次发布后立刻发现问题需要紧急出补丁包用 new1、new2 这种后缀区分比每次都改版本号来得更直接。3.1 测试版本的完成度边界beta2 处在什么位置我的定义是核心功能全部可用但外围辅助流程还有明显简化空间。具体来说已完成文件扫描、模板生成、FTP 上传、预览页生成、路径检查未完成多站点配置管理一次发布多个站点、自动压缩资源文件、断点续传按当时的使用反馈来看核心路径扫描 → 预览 → 上传的完成度足够支撑日常使用。我希望 beta2 能成为第一个面向非技术用户的“公开测试版”所以宁可打包晚一天也要把已知的几个关键问题处理干净。3.2 新版修订的命名规则new2这个后缀是我个人习惯同一天同一个版本出了第二或第三次修订。对这种小工具来说与其把版本号改成 beta3、beta4不如用 new1、new2 更直接原因是我可以一眼看出某个包是哪一天的第几次打包对找回旧代码、对比差异非常有用。但这种方法也有明显的坑时间久了之后靠文件名根本看不出 new1 和 new2 的具体区别。所以包内我固定放一个CHANGELOG.txt记录每次修订的内容。比如下面这个片段就是当时写在里面的2020-05-23 beta2 new2: - fix: 修复 Windows 下中文目录名导致 FTP 上传路径错误的问题 - fix: 修复预览页在 PHP 7.3 上的一个兼容性警告 - update: 调整默认页面排序index.html 优先我认为“修改记录至少保留一份文本文件”这点特别值得强调——很多个人项目做完就忘了为什么某些代码长这样等到再想维护时只能靠猜。这份 CHANGELOG 后来帮我省了大量回忆成本。3.3 打包前的质量检查清单打包动作本身很机械但打包前我应该做哪些检查是踩过两次坑之后总结出来的确认所有文件均已保存且没有残留临时文件*.tmp、*.swp确认 FTP 上传功能在 PHP 7.0、7.2、7.4 三个版本上均测试通过确认预览页的样式不依赖外网 CDN避免联网时正常、断网时变裸页确认包内 README 中的版本号与 CHANGELOG 中的版本号一致确认解压路径全程无中文这个早期版本对中文目录支持有 bug我在这张清单上栽过不止一次有一次更新了功能代码但忘了改 README 里的版本号有一次打包时多选中了一个本地调试用的临时目录结果整个包多出几 MB 的冗余文件。后来我按照这个清单逐项核对打包出错的概率基本降为零。4. 解包复盘代码里的细节和当年踩过最深的坑这次重新解压 beta2 new2我对着源码复盘了一遍最大的感受是很多当时看不出价值的设计过了两三年再看恰恰是让整个项目能跑起来的“隐藏护城河”。4.1 代码结构入口、配置、能力三分离源码根目录下的文件组织是这样的deweb/ index.php # 入口文件负责初始化流程 config.sample.php # 配置模板含 FTP、目录、功能开关 lib/ scanner.php # 目录扫描与文件解析 preview.php # 预览页生成器 uploader.php # FTP 上传执行器 checker.php # 路径检查与资源依赖分析 assets/ basic.css # 预览页的最小样式 icon/ # 页面图标摊大饼风格非必须 CHANGELOG.txt README.md入口、配置、能力三部分分离是我现阶段自己比较喜欢的风格。入口文件只做流程编排不懂业务逻辑配置文件放用户可调项lib 目录放具体能力实现。这个分层的好处是即使代码写得再烂想换掉其中一块比如把 FTP 上传换成 SFTP只需要替换uploader.php其他地方不用大改。4.2 几个“非标准但有效”的做法beta2 里有几处写法放在教科书上看可能不太符合规范但在当时的小工具场景下是合理取舍。一是调用本地 PHP 命令时我采用组合环境变量的方式来替代 IPC 访问系统命令不我实际上做的是通过exec()调/usr/bin/php -v来检测 PHP 是否可用。这不是最优雅的方式但它不依赖系统 PATH 的配置顺序避免了一些服务器上环境变量不一致带来的麻烦。二是预览页的 HTML 输出我直接用字符串拼嵌套转义函数。为了把输出过程尽量压缩我放弃了三方模板引擎改为在 PHP 内联拼接 HTML。这让代码读起来有点破破烂烂但换来的是零依赖用户拿去就能跑。三是扫描文件时用了递归调用加静态变量缓存在目录层级特别深时超过 5 层会出现性能下降。但我当时设计的适用场景是小微型站点普通页面最多就四层目录所以这个限制并不影响实际使用反而让代码实现简单了很多。4.3 中文目录名跨平台问题我在 beta2 new2 里最关键的修复这个是我记忆最深刻的 bug。测试时在 Windows 环境下跑 FTP 上传目标服务器是 LinuxCentOS 7只要本地文件夹名或子目录名包含中文比如“项目资料”上传后目录结构就乱套文件跑到了错误的位置甚至部分文件直接丢失。最初我以为是编码问题试过把文件名转成 UTF-8、GBK都没用。后来一行一行排查才发现uploader.php里拼路径时用了str_replace(\\, /, $path)只把 Windows 反斜杠改成正斜杠却忘了对目录中的中文做 URL 编码rawurlencode服务器端的 FTP 收到非 ASCII 字符路径时就无法正确解析。修复方案是加了一个统一的路径过滤函数function safe_ftp_path($path) { $path str_replace(\\, /, $path); $parts explode(/, $path); foreach ($parts as $p) { if (!preg_match(/^[a-zA-Z0-9_\-\.]$/, $p)) { $p rawurlencode($p); } } return implode(/, $parts); }每个路径段先检测是否只包含安全字符不是的话再做 URL 编码。这样中文目录名在 FTP 传输时就能被服务器正确解析。这个补丁从测试到合入大约花了半天是 beta2 new2 最重要的一个修复。当时我还特意写了一个测试用例本地建一个“测试 目录/子目录/index.html”的嵌套结构验证上传后目标服务器能精确还原目录树。最终测试通过后我才敢把包标记为 new2 发出去。5. 如果将这个包“现代化”重新设计的三个方向复盘完旧代码我顺手在脑内做了一次“现代化改造”的设计推演。如果现在重新做同类型工具beta2 里的很多设计可以升级但核心价值不会变降低非技术用户的发布门槛。5.1 用 PHP 内置 web server 替代手动配置这部分实质上在 beta2 已经用上了但可以做得更彻底提供一键启动脚本start.commandmacOS和start.batWindows用户双击就能启动预览服务器并自动打开浏览器。省掉手动敲命令这一步最能体现对小白用户的友好度。5.2 支持多套配置方案并行beta2 一次只能配置一个站点。实际场景中一个人可能同时维护两三个小站点每次都改配置再发布不太方便。现代化版本可以增加“站点配置集合”概念用 JSON 文件保存多个站点的配置发布时按名称选择自动切换。这不需要复杂 UI在入口页面下拉选择即可。5.3 引入“元数据驱动”的资源管理思路另一个可以扩展的方向是给每个站点增加一个site.json里面写清站点标题、描述、作者信息、页面排序等。deweb 可以读取这份文件并自动生成更完整的站点预览页和 SEO 基础标签。这比纯靠扫描 HTML 推断更准确也给了用户一定程度的“无代码配置站点信息”能力。这些设想最终没有在 beta2 里实现原因是开发重心已经转移加之这套工具目标定位是“小而美”如果再继续堆功能反而容易从一个轻量工具变成一个“简易 CMS”失去原本的定位。6. 经验沉淀从 deweb beta2 中提炼的复盘清单翻了旧包之后我脑子里留下的不仅是对代码的回忆还有几件值得分享的事情。第一命名规范要能被人未来的自己读懂。我现在仍然提倡在压缩包文件名里放日期、版本、修订序列但强烈建议在包内写 CHANGELOG否则三个月后你根本分不清 new1 和 new5 的区别。时间越长这句话的价值越大。第二给非技术用户做工具一定要减少心智负担。不是每个人都了解 FTP、目录权限和路径编码你的工具越能替用户挡掉细节越有可能被真正用起来。beta2 里“扫描目录自动生成预览页”的设计本质上就是把“检查文件是否齐全”这件小事从用户身上剥离出来用户只需要看一眼预览页有没有问题然后点发布即可。这个思路后来我做任何相关项目时都在沿用。第三跨平台问题永远比自己想象的多。在我这次修复中一个看似简单的str_replace反斜杠转正斜杠都藏着问题因为路径里的中文名称在 FTP 协议栈上根本过不了关。如果你做的项目涉及多平台文件传输建议把“文件名编码 特殊字符 路径分隔符”作为专项测试项而不是临到头靠用户反馈。第四残缺的工具也可以有实战价值。我反复想过很多次把 deweb 归为“未完成产品”还是“实用工具”。最终我的答案是只要核心路径完整可用剩下的功能缺口不影响它在特定场景下发光。beta2 的定位是把静态页面快速发布这件事做到简单可靠它做到了。这点对我之后做其他小工具的选型也有启发一个人不用什么都做把一件事做好就够了。7. 说在最后如果你也翻出了多年没打开的旧压缩包我的建议是别着急删除解压看看。你可能会发现代码里的设计和问题排查过程比你记忆中的更成熟也更能看出真实的成长轨迹。deweb 这个包我不打算再改了它的使命在 2020 年就已经完成用它顶过好几个朋友从静态稿到线上发布的最后一公里也在那段时间让我对“工具”和“使用者”的关系想得更清晰。以后如果真有人需要同类功能我会基于现在的思路重写一个更现代、更友好的版本但核心哲学不会变——让复杂的事情变简单而不是让简单的事情变得更复杂。如果你也在琢磨类似的轻量工具希望这篇复盘能给你一点参考。打包时的new2标记现在回头看更像是“终于把该踩的坑都踩完了”的落点而不是一个简单的修订号。本文还有配套的精品资源点击获取
复盘 deweb beta2：一个PHP写的静态网页快速发布工具
简介DeWeb 是一套帮助 Delphi 开发者将传统桌面程序快速转换为网页应用的框架资源包定位清晰面向希望继续使用 Delphi 完成 Web 端开发的程序员无需学习 HTML、JavaScript、Java、PHP、ASP、C# 等语言即可生成支持手机、平板等多客户端访问的页面。压缩包共 2669 个文件整体约 24.59MB典型文件包括 pas 源码、dfm 窗体、dproj/dpk 工程与包文件、dcu 编译单元、js/css/html 前端资源、res/dcr 资源及 bat 构建脚本分别对应核心逻辑、界面布局、项目配置、预编译产物与自动化操作目录结构清晰便于按需查阅。资源附带 Delphi 10.1/10.2/10.3 版本的 dcu 文件、IcsV858 控件安装步骤、DelphiWeb 演示工程及新建页面的完整注册流程开发者可结合 main.pas 中的 RegisterClass/UnRegisterClass 用法快速上手。目前已有 1071 人学习下载尤其适合需要以 Delphi 统一前后端、快速交付响应式 Web 应用的团队或个人参考与二次开发。 前几天整理网盘备份在“存档不删”目录里翻出一个压了好几年的压缩包文件名是deweb2020-05-23 beta2 new2.rar。解压之前我还愣了一下等看到里面的文件结构才想起来这是当年自己做的一套轻量型网站快速发布工具前前后后迭代了三个多月最后停在 beta2 这个版本上。这东西算不上什么大项目但确实解决过一批人的实际问题不想碰服务器命令不想碰数据库只想把几个网页扔上线。我把它打成包发给过几个朋友后来因为忙着别的事就搁置了压缩包也就一直躺在网盘里。现在重新翻出来看里面的代码、注释、打包脚本和那份“发布前检查清单”反而比当时写的时候更有嚼头。这篇就借着这个压缩包把我当时的设计思路、技术选型、版本迭代过程和踩过的坑完整梳理一遍。1. deweb beta2 到底是什么一个“网页快速发布工具”的自白先说清楚这个东西的定位。deweb 的全称是 “Deliverable Web”我当时的想法很简单做一个让普通用户也能在十分钟内把一套静态网页发布到服务器上的小工具。它不是一个 CMS内容管理系统没有后台管理界面也没有数据库依赖核心就三个能力接收一个文件夹内含 HTML、CSS、JS、图片等静态资源自动分析文件结构生成一套可直接运行的站点配置通过 FTP 或本地目录方式发布到目标位置附带一个简单的在线预览页为什么做这个因为我当时遇到一个高频需求周围不少朋友在做个人作品集、小型活动页面、临时宣传页内容就是几个静态页面不需要动态功能。但他们卡在两步上一是本地做好网页后不知道怎么上传二是上传后访问不了要么是目录路径不对要么是文件权限有问题。市面上的工具分两种一种是前端构建工具Webpack、Gulp 这类定位是开发期用一般用户玩不转另一种是一键建站平台又太重动不动让你选模板、绑域名反而把简单的事搞复杂。我想要的中间地带是你给我一个文件夹我给你一个能跑的网站。deweb 就是往这个方向做的。beta2 是 2020 年 5 月 23 日定型的测试版本。文件命名里的new2是因为同一天我打包了三次前两次不是漏了文件就是版本号没更新第三次才确认无误。这个细节后面会展开讲打包这件事儿真不光是点一下“压缩”那么简单。2. 核心功能拆解模板导入、动态配置与本地预览2.1 文件结构解析不写代码的“配置即服务”deweb 最核心的逻辑是对用户传入的文件夹做静态分析。我当时用 PHP 写了一个入口脚本index.php它做以下几件事扫描目录中的所有文件按扩展名分组。HTML 归为页面文件CSS/JS归为资源文件图片归为媒体文件其他归为附件。读取每个 HTML 文件的第一行title标签自动把它作为页面名称。如果检测到nginx.conf.example或.htaccess.example自动生成对应的转发规则。这套逻辑把“手动配置服务器”压缩成了“扫描 自动生成”。用户不需要知道 404 页面怎么配、伪静态规则怎么写工具会基于已有的文件结构推断出来。比如当你有一个blog/index.html时工具会默认生成一条/blog到/blog/index.html的裸域名访问规则。2.2 发布流程的三段式设计整个发布流程我用了一张流程图来设计文字说明版本第一步选择本地目录就是你的网站文件夹第二步配置发布目标FTP 服务器信息或本地目录路径第三步预览 确认工具先自动生成一份预览页确认无误后执行发布第三步里的预览页是我觉得比较有价值的设计。在真正上传之前deweb 会生成一个.deweb_preview.html把这个站点的所有页面、资源文件、附件列成一张表格显示文件大小、文件类型、预计上传时间。这样做的好处是避免一种常见翻车传上去之后发现漏了这个 JS、少了个 CSS网站样式全崩了。表格里还有一个“循环依赖检查”的选项用来检测 HTML 中互相引用的资源是否都存在。因为是纯静态站点循环依赖出现的概率不高但我在测试时遇到过link relstylesheet hrefstyle.css写成了href./css/style.css但实际文件在css/style.css这种路径拼写错误。这个检查能提前把你从“传上去之后啥也不显示”的尴尬里救回来。2.3 本地预览服务器一个小但关键的细节直接双击 HTML 文件也能预览但浏览器会限制部分能力比如 fetch 本地文件。deweb 内置了一个极简的 PHP 开发服务器启动命令php -S 127.0.0.1:8080 -t ./这条命令会把当前目录作为站点根目录启动本地服务。基于这个原因deweb 的运行环境要求是 PHP 5.6 以上因为php -S是 PHP 5.4 引入的这个门槛在 2020 年完全不是问题。选择 PHP 而不是 Node.js 的原因很朴素那时候我的目标是让用户在自己电脑上就能跑起来Windows 用户装了 PHP 的比装了 Node 的多得多而且 PHP 自带 HTTP 服务省去 npm install 的依赖折腾。3. 从 beta2 new2 这个命名看版本管理的门道deweb2020-05-23 beta2 new2.rar这串名字看着随意其实信息量不小。它包含三个关键字段日期2020-05-23、版本beta2、修订序号new2。这正好对应了轻量工具开发中常用的“三段式存档法”。当时这么命名是因为有两次发布后立刻发现问题需要紧急出补丁包用 new1、new2 这种后缀区分比每次都改版本号来得更直接。3.1 测试版本的完成度边界beta2 处在什么位置我的定义是核心功能全部可用但外围辅助流程还有明显简化空间。具体来说已完成文件扫描、模板生成、FTP 上传、预览页生成、路径检查未完成多站点配置管理一次发布多个站点、自动压缩资源文件、断点续传按当时的使用反馈来看核心路径扫描 → 预览 → 上传的完成度足够支撑日常使用。我希望 beta2 能成为第一个面向非技术用户的“公开测试版”所以宁可打包晚一天也要把已知的几个关键问题处理干净。3.2 新版修订的命名规则new2这个后缀是我个人习惯同一天同一个版本出了第二或第三次修订。对这种小工具来说与其把版本号改成 beta3、beta4不如用 new1、new2 更直接原因是我可以一眼看出某个包是哪一天的第几次打包对找回旧代码、对比差异非常有用。但这种方法也有明显的坑时间久了之后靠文件名根本看不出 new1 和 new2 的具体区别。所以包内我固定放一个CHANGELOG.txt记录每次修订的内容。比如下面这个片段就是当时写在里面的2020-05-23 beta2 new2: - fix: 修复 Windows 下中文目录名导致 FTP 上传路径错误的问题 - fix: 修复预览页在 PHP 7.3 上的一个兼容性警告 - update: 调整默认页面排序index.html 优先我认为“修改记录至少保留一份文本文件”这点特别值得强调——很多个人项目做完就忘了为什么某些代码长这样等到再想维护时只能靠猜。这份 CHANGELOG 后来帮我省了大量回忆成本。3.3 打包前的质量检查清单打包动作本身很机械但打包前我应该做哪些检查是踩过两次坑之后总结出来的确认所有文件均已保存且没有残留临时文件*.tmp、*.swp确认 FTP 上传功能在 PHP 7.0、7.2、7.4 三个版本上均测试通过确认预览页的样式不依赖外网 CDN避免联网时正常、断网时变裸页确认包内 README 中的版本号与 CHANGELOG 中的版本号一致确认解压路径全程无中文这个早期版本对中文目录支持有 bug我在这张清单上栽过不止一次有一次更新了功能代码但忘了改 README 里的版本号有一次打包时多选中了一个本地调试用的临时目录结果整个包多出几 MB 的冗余文件。后来我按照这个清单逐项核对打包出错的概率基本降为零。4. 解包复盘代码里的细节和当年踩过最深的坑这次重新解压 beta2 new2我对着源码复盘了一遍最大的感受是很多当时看不出价值的设计过了两三年再看恰恰是让整个项目能跑起来的“隐藏护城河”。4.1 代码结构入口、配置、能力三分离源码根目录下的文件组织是这样的deweb/ index.php # 入口文件负责初始化流程 config.sample.php # 配置模板含 FTP、目录、功能开关 lib/ scanner.php # 目录扫描与文件解析 preview.php # 预览页生成器 uploader.php # FTP 上传执行器 checker.php # 路径检查与资源依赖分析 assets/ basic.css # 预览页的最小样式 icon/ # 页面图标摊大饼风格非必须 CHANGELOG.txt README.md入口、配置、能力三部分分离是我现阶段自己比较喜欢的风格。入口文件只做流程编排不懂业务逻辑配置文件放用户可调项lib 目录放具体能力实现。这个分层的好处是即使代码写得再烂想换掉其中一块比如把 FTP 上传换成 SFTP只需要替换uploader.php其他地方不用大改。4.2 几个“非标准但有效”的做法beta2 里有几处写法放在教科书上看可能不太符合规范但在当时的小工具场景下是合理取舍。一是调用本地 PHP 命令时我采用组合环境变量的方式来替代 IPC 访问系统命令不我实际上做的是通过exec()调/usr/bin/php -v来检测 PHP 是否可用。这不是最优雅的方式但它不依赖系统 PATH 的配置顺序避免了一些服务器上环境变量不一致带来的麻烦。二是预览页的 HTML 输出我直接用字符串拼嵌套转义函数。为了把输出过程尽量压缩我放弃了三方模板引擎改为在 PHP 内联拼接 HTML。这让代码读起来有点破破烂烂但换来的是零依赖用户拿去就能跑。三是扫描文件时用了递归调用加静态变量缓存在目录层级特别深时超过 5 层会出现性能下降。但我当时设计的适用场景是小微型站点普通页面最多就四层目录所以这个限制并不影响实际使用反而让代码实现简单了很多。4.3 中文目录名跨平台问题我在 beta2 new2 里最关键的修复这个是我记忆最深刻的 bug。测试时在 Windows 环境下跑 FTP 上传目标服务器是 LinuxCentOS 7只要本地文件夹名或子目录名包含中文比如“项目资料”上传后目录结构就乱套文件跑到了错误的位置甚至部分文件直接丢失。最初我以为是编码问题试过把文件名转成 UTF-8、GBK都没用。后来一行一行排查才发现uploader.php里拼路径时用了str_replace(\\, /, $path)只把 Windows 反斜杠改成正斜杠却忘了对目录中的中文做 URL 编码rawurlencode服务器端的 FTP 收到非 ASCII 字符路径时就无法正确解析。修复方案是加了一个统一的路径过滤函数function safe_ftp_path($path) { $path str_replace(\\, /, $path); $parts explode(/, $path); foreach ($parts as $p) { if (!preg_match(/^[a-zA-Z0-9_\-\.]$/, $p)) { $p rawurlencode($p); } } return implode(/, $parts); }每个路径段先检测是否只包含安全字符不是的话再做 URL 编码。这样中文目录名在 FTP 传输时就能被服务器正确解析。这个补丁从测试到合入大约花了半天是 beta2 new2 最重要的一个修复。当时我还特意写了一个测试用例本地建一个“测试 目录/子目录/index.html”的嵌套结构验证上传后目标服务器能精确还原目录树。最终测试通过后我才敢把包标记为 new2 发出去。5. 如果将这个包“现代化”重新设计的三个方向复盘完旧代码我顺手在脑内做了一次“现代化改造”的设计推演。如果现在重新做同类型工具beta2 里的很多设计可以升级但核心价值不会变降低非技术用户的发布门槛。5.1 用 PHP 内置 web server 替代手动配置这部分实质上在 beta2 已经用上了但可以做得更彻底提供一键启动脚本start.commandmacOS和start.batWindows用户双击就能启动预览服务器并自动打开浏览器。省掉手动敲命令这一步最能体现对小白用户的友好度。5.2 支持多套配置方案并行beta2 一次只能配置一个站点。实际场景中一个人可能同时维护两三个小站点每次都改配置再发布不太方便。现代化版本可以增加“站点配置集合”概念用 JSON 文件保存多个站点的配置发布时按名称选择自动切换。这不需要复杂 UI在入口页面下拉选择即可。5.3 引入“元数据驱动”的资源管理思路另一个可以扩展的方向是给每个站点增加一个site.json里面写清站点标题、描述、作者信息、页面排序等。deweb 可以读取这份文件并自动生成更完整的站点预览页和 SEO 基础标签。这比纯靠扫描 HTML 推断更准确也给了用户一定程度的“无代码配置站点信息”能力。这些设想最终没有在 beta2 里实现原因是开发重心已经转移加之这套工具目标定位是“小而美”如果再继续堆功能反而容易从一个轻量工具变成一个“简易 CMS”失去原本的定位。6. 经验沉淀从 deweb beta2 中提炼的复盘清单翻了旧包之后我脑子里留下的不仅是对代码的回忆还有几件值得分享的事情。第一命名规范要能被人未来的自己读懂。我现在仍然提倡在压缩包文件名里放日期、版本、修订序列但强烈建议在包内写 CHANGELOG否则三个月后你根本分不清 new1 和 new5 的区别。时间越长这句话的价值越大。第二给非技术用户做工具一定要减少心智负担。不是每个人都了解 FTP、目录权限和路径编码你的工具越能替用户挡掉细节越有可能被真正用起来。beta2 里“扫描目录自动生成预览页”的设计本质上就是把“检查文件是否齐全”这件小事从用户身上剥离出来用户只需要看一眼预览页有没有问题然后点发布即可。这个思路后来我做任何相关项目时都在沿用。第三跨平台问题永远比自己想象的多。在我这次修复中一个看似简单的str_replace反斜杠转正斜杠都藏着问题因为路径里的中文名称在 FTP 协议栈上根本过不了关。如果你做的项目涉及多平台文件传输建议把“文件名编码 特殊字符 路径分隔符”作为专项测试项而不是临到头靠用户反馈。第四残缺的工具也可以有实战价值。我反复想过很多次把 deweb 归为“未完成产品”还是“实用工具”。最终我的答案是只要核心路径完整可用剩下的功能缺口不影响它在特定场景下发光。beta2 的定位是把静态页面快速发布这件事做到简单可靠它做到了。这点对我之后做其他小工具的选型也有启发一个人不用什么都做把一件事做好就够了。7. 说在最后如果你也翻出了多年没打开的旧压缩包我的建议是别着急删除解压看看。你可能会发现代码里的设计和问题排查过程比你记忆中的更成熟也更能看出真实的成长轨迹。deweb 这个包我不打算再改了它的使命在 2020 年就已经完成用它顶过好几个朋友从静态稿到线上发布的最后一公里也在那段时间让我对“工具”和“使用者”的关系想得更清晰。以后如果真有人需要同类功能我会基于现在的思路重写一个更现代、更友好的版本但核心哲学不会变——让复杂的事情变简单而不是让简单的事情变得更复杂。如果你也在琢磨类似的轻量工具希望这篇复盘能给你一点参考。打包时的new2标记现在回头看更像是“终于把该踩的坑都踩完了”的落点而不是一个简单的修订号。本文还有配套的精品资源点击获取