环境与约束记录

本文件记录框架开发所依托的线上环境事实，供后续开发与部署决策参考。

站点

• 站点地址：https://ui.phli.cn/
• 站点用途：飞立（plui）响应式 CSS 框架的开发与文档站
• 站点根目录（服务器侧）：/home2/phlicn/public_html/ui.phli.cn
• 主机类型：cPanel 虚拟主机（共享主机），同一台主机下还运行着 demo.phli.cn 与 speed.phli.cn
• 共享资源说明：多站点共享同一份 PHP 进程池、同一套配额与同一块磁盘 IO。构建期在本机进行、站点只放静态产物，正是为了避免在共享主机上跑任何编译任务。

运行时

• Web 服务器：LiteSpeed
• PHP：8.5.12
• HTTPS：可用，站点强制走 https
• 扩展：不需要在站点侧运行 PHP 业务逻辑，本项目只投放静态 CSS / JS / HTML / Markdown

现有服务器配置文件的处理约定

根目录 .htaccess（890 字节）是 cPanel 自动生成的默认内容，只包含 error_log 段与 ea-php85 handler，没有合并任何业务规则。

约定如下：

1. 默认不改。本框架是纯静态 CSS 项目，不需要任何重写规则。
2. 如果将来确实需要重写规则（例如给 .md 加 MIME 或做目录首页），必须先备份原文件再合并，保留 cPanel 原段不被覆盖。
3. 同样地，.user.ini、.fileops_state.php、fileops.php、.well-known/、cgi-bin/ 都属于 cPanel 与临时通道，不属于本项目，不要改动。

构建与部署的硬约束

• 站点上没有 Node、npm、git 或任何构建工具链，也不应该安装。共享主机的权限与稳定性都不适合跑构建。
• 因此 dist/ 里的成品必须在本地 Node 环境构建完成后再上传，站点只承担托管与展示。
• 本地构建环境已核查：Node v24.22.1、npm 11.19.1、git 2.39.5 可用。
• 产物上传前应至少跑一次格式与语法校验（见 build/README.md）。build/build.mjs 每次构建都会自动做花括号 / 分号配平、@import 检查与自引用自定义属性检查。

临时文件接口说明

站点根目录的 fileops.php 是宿主临时放置的 PHP 文件接口，用途是让助手在授权期内读写站点文件。

• 它是临时通道，用完应当清理，不是本项目的长期依赖。
• 本项目（CSS 框架）不依赖它在运行期做任何事情；删除它之后，站点上的 CSS、文档、示例页全部照常工作。
• 接口密钥属于敏感凭据，不写入站点任何文件，也不提交进版本库。

已知的服务器行为

• 访问 https://ui.phli.cn/ 在没有 index.html 时返回 LiteSpeed 默认 404 页。
• .md 文件直接访问返回 403：这是 cPanel/LiteSpeed 按后缀拦截的结果，不是文件损坏——同一份文件通过文件接口读取的 sha256 与本地一致。处理办法见下节。
• 对静态页面发 POST 请求返回 200（返回的是页面 HTML 本身）。这一点会影响 src/common.js 的自动配置拉取，详见 COMMONJS.md 第 5 节。

文档形态与 .md 拦截的应对

站点按后缀拦截 .md，所以：

1. 每篇 Markdown 都配一份同名 .html，浏览器访问 .html。
2. .html 由 build/build-docs.mjs 从同一份 Markdown 生成，不要手工编辑 .html，改 .md 后重新生成。
3. 两者的对应关系写在 README.md 的文档索引表里。

之所以不直接改 .htaccess 放行 .md：那是 cPanel 的默认文件，改动需要备份与合并，属于服务器层面的变更；当前用双份文件解决，代价更低、可回滚性更好。这个选择记在 DECISIONS.md 的 D10。

本页由 build/build-docs.mjs 从同名 Markdown 生成，请修改 .md 后重新生成，不要手工编辑本文件。