简介

本文件聚焦 DouPHP 的路径配置与 URL 重写机制，覆盖管理员目录（ADMIN_DIR）、API 目录（API_DIR）、小程序目录（MINIPROGRAM_DIR）的配置方法；说明后台 URL 重写开关（ADMIN_REWRITE）的作用与启用方式；给出不同部署环境下的路径配置示例（虚拟主机、Docker 容器等）；解释路径配置对 SEO 和访问性能的影响；提供自定义目录结构的配置方法与最佳实践；并说明多站点部署时的路径隔离策略。

项目结构

DouPHP 通过统一的引导流程加载站点配置，定义关键常量与路径，再由各入口（前台、后台、API）分别进行路由分发。小程序端通过运行时配置文件获取站点根地址与 API 地址。

graph TB
A["应用根目录"] --> B["core/bootstrap.php<br/>定义 ROOT_PATH / CONFIG_PATH / STORAGE_PATH"]
B --> C["config/config.php<br/>定义 ADMIN_DIR / API_DIR / MINIPROGRAM_DIR / ADMIN_REWRITE"]
B --> D["core/bootstrap.php<br/>定义 API_PATH / ADMIN_PATH / MINIPROGRAM_PATH"]
A --> E[".htaccess<br/>URL 重写规则：/api/* → api/index.php?route=...<br/>/admin/* → admin/index.php?route=...<br/>/* → index.php?route=..."]
A --> F["index.php<br/>前台入口"]
A --> G["admin/index.php<br/>后台入口"]
A --> H["api/index.php<br/>API 入口"]
I["miniprogram/*/config/site.ts<br/>root_url / mp_url / rewrite_enable"] --> J["小程序前端调用 API"]

核心组件

• 站点常量与路径定义
  • 管理员目录：ADMIN_DIR（默认 admin，可动态覆盖）
  • API 目录：API_DIR（默认 api）
  • 小程序目录：MINIPROGRAM_DIR（默认 miniprogram）
  • 后台 URL 重写开关：ADMIN_REWRITE（默认 false）
• 引导阶段路径计算
  • 在 core/bootstrap.php 中根据上述常量生成 API_PATH、ADMIN_PATH、MINIPROGRAM_PATH
• 入口与路由
  • 前台 index.php、后台 admin/index.php、API api/index.php 均将 ?route=... 写入 Request，再交由各自 Resolver 解析
• 小程序运行配置
  • miniprogram/*/config/site.ts 暴露 root_url、mp_url、rewrite_enable，供小程序前端使用

架构总览

下图展示请求从 Web 服务器到 PHP 入口再到路由分发的完整链路，以及 URL 重写如何把美观的 URL 映射到实际入口参数。

sequenceDiagram
participant Client as "客户端"
participant Apache as "Web 服务器(.htaccess)"
participant Front as "前台入口 index.php"
participant Admin as "后台入口 admin/index.php"
participant Api as "API 入口 api/index.php"
participant Router as "路由分发(Resolver)"
Client->>Apache : GET /admin/dashboard
Apache->>Admin : 重写为 admin/index.php?route=admin/dashboard
Admin->>Router : setRouteString("admin/dashboard")
Router-->>Admin : 匹配控制器/方法 -> 响应
Client->>Apache : GET /api/product
Apache->>Api : 重写为 api/index.php?route=product
Api->>Router : setRouteString("product")
Router-->>Api : 匹配控制器/方法 -> JSON 响应
Client->>Apache : GET /product/detail
Apache->>Front : 重写为 index.php?route=product/detail
Front->>Router : setRouteString("product/detail")
Router-->>Front : 匹配控制器/方法 -> HTML 响应

详细组件分析

管理员目录（ADMIN_DIR）配置

• 默认值与覆盖
  • 默认值为 admin
  • 可通过传入 $admining 变量覆盖，从而改变后台物理目录名
• 引导阶段生效
  • core/bootstrap.php 在加载 config/config.php 前会尝试读取 storage/state/admin_dir.php，若存在则先引入以定义 $admining，再加载 config/config.php 得到最终 ADMIN_DIR
• 工具支持
  • 后台提供“自定义后台目录”功能，可在不手动改名的情况下准备重定向脚本，完成安全迁移并跳转到新后台入口

flowchart TD
Start(["请求进入"]) --> LoadState["加载 storage/state/admin_dir.php如存在"]
LoadState --> LoadConfig["加载 config/config.php<br/>define('ADMIN_DIR', ...)"]
LoadConfig --> BootstrapPaths["bootstrap.php 定义 ADMIN_PATH = ROOT_PATH + ADMIN_DIR"]
BootstrapPaths --> UseInRoutes["后台入口使用 ADMIN_PATH 加载路由/中间件"]

API 目录（API_DIR）配置

• 默认值为 api
• bootstrap 阶段据此生成 API_PATH，供 API 入口与路由层使用
• API 入口统一接收 ?route=... 并通过 ApiResolver 解析到具体控制器与方法

小程序目录（MINIPROGRAM_DIR）配置

• 默认值为 miniprogram
• bootstrap 阶段生成 MINIPROGRAM_PATH
• 小程序前端通过 miniprogram/*/config/site.ts 中的 root_url 与 mp_url 访问后端，rewrite_enable 镜像站点伪静态开关

URL 重写（ADMIN_REWRITE）与全站伪静态

• 后台 URL 重写开关
  • ADMIN_REWRITE 用于标识后台是否启用 URL 重写（默认 false）。注意：当前 .htaccess 已统一将 /admin/* 重写至 admin/index.php?route=...，因此该常量更多作为业务逻辑标记使用
• 全站伪静态
  • .htaccess 定义了 /api/、/admin/、/* 的重写规则，将美观 URL 转为 index.php?route=... 或对应入口的 route 参数
• 前端 URL 生成
  • theme/default/js/route.js 在 rewrite 开启时直接拼接路径，否则回退到 index.php?route=...
  • UrlBuilder 同样依据 site.rewrite 决定输出形式

flowchart TD
A["浏览器请求 /admin/login"] --> B[".htaccess 匹配 ^admin/(.+)$"]
B --> C["转发到 admin/index.php?route=admin/login"]
C --> D["后台入口读取 route 字符串"]
D --> E["AdminResolver 解析到控制器/方法"]
E --> F["返回页面或 JSON"]

路由解析与中间件栈

• 后台 AdminResolver
  • 基于声明式路由表匹配模块/动作/子路径，设置 Request 的 baseUrl、route、params，并组装中间件链
• API ApiResolver
  • 与后台类似，但面向 JSON 响应，默认中间件包含安全头、信任代理、限流，可选用户认证

依赖关系分析

• 配置到路径的依赖
  • config/config.php 定义 ADMIN_DIR/API_DIR/MINIPROGRAM_DIR/ADMIN_REWRITE
  • core/bootstrap.php 读取配置并定义 API_PATH/ADMIN_PATH/MINIPROGRAM_PATH
• 入口到路由的依赖
  • 三个入口文件均依赖各自的 Resolver 进行路由分发
• 前端到后端的依赖
  • 小程序前端依赖 site.ts 中的 root_url/mp_url/rewrite_enable
  • 前台 JS 依赖 theme/default/js/route.js 与 UrlBuilder 的 rewrite 行为

graph LR
CFG["config/config.php"] --> BOOT["core/bootstrap.php"]
BOOT --> PATHS["API_PATH / ADMIN_PATH / MINIPROGRAM_PATH"]
PATHS --> FRONT["index.php"]
PATHS --> ADMIN["admin/index.php"]
PATHS --> API["api/index.php"]
HTACCESS[".htaccess"] --> FRONT
HTACCESS --> ADMIN
HTACCESS --> API
SITE_TS["miniprogram/*/config/site.ts"] --> MP["小程序前端"]

性能与SEO影响

• 伪静态的优势
  • 更短、可读性更强的 URL 有利于搜索引擎抓取与收录
  • 减少查询参数，利于缓存层（CDN/反向代理）命中
• 关闭伪静态的影响
  • URL 形如 index.php?route=...，不利于 SEO，且可能增加重复内容风险
• 建议
  • 生产环境开启伪静态（确保 .htaccess 生效），并在 URL 生成处遵循 rewrite 模式
  • 保持 URL 稳定，避免频繁变更路径导致外链失效

故障排查指南

• 无法访问后台或 API
  • 检查 .htaccess 是否启用 RewriteEngine 且规则未被服务器禁用
  • 确认入口文件能被 Web 服务器正确解析（PHP 环境正常）
• 后台目录改名后 404
  • 使用后台“自定义后台目录”工具进行迁移，避免直接 rename 导致的句柄占用问题
• 小程序无法请求 API
  • 核对 miniprogram/*/config/site.ts 中的 mp_url 是否正确指向线上域名
  • 确认 rewrite_enable 与站点一致
• URL 生成异常
  • 检查 theme/default/js/route.js 与 UrlBuilder 的 rewrite 开关是否与 .htaccess 一致

结论

DouPHP 通过集中化的配置与引导流程，将管理员、API、小程序等子系统的目录与路径解耦，便于在不同部署环境下灵活调整。配合 .htaccess 的 URL 重写与前端 URL 生成逻辑，既能提升 SEO 友好度，也能优化缓存命中率。借助内置的“自定义后台目录”工具与运行时配置，可实现安全的目录迁移与多站点路径隔离。

附录：部署示例与最佳实践

• 虚拟主机（共享主机）

  • 将站点根目录指向 Web 根目录
  • 确保 .htaccess 生效（AllowOverride All）
  • 如需隐藏 admin 目录，修改 config/config.php 中的 ADMIN_DIR 并使用后台工具迁移
  • 小程序 site.ts 中的 root_url/mp_url 需填写真实域名

• Docker 容器

  • 挂载站点目录到容器，确保 .htaccess 随代码一起部署
  • 在 Nginx/Apache 容器中启用 URL 重写
  • 环境变量或编排层注入数据库与密钥，保持 config/config.php 最小化敏感信息
  • 小程序 site.ts 的 mp_url 指向容器对外暴露的域名或网关路径

• 多站点部署（同机多实例）

  • 每个站点独立目录与数据库，避免路径冲突
  • 通过不同的域名或子域名区分站点，site.ts 中 root_url/mp_url 按站点配置
  • 如需共享资源，使用 CDN 或独立存储桶，避免跨站污染
  • 后台目录命名差异化（例如 admin_a、admin_b），降低误访问风险

• 自定义目录结构与最佳实践

  • 优先使用后台“自定义后台目录”工具迁移，避免进程句柄占用
  • 保持 API_DIR/MINIPROGRAM_DIR 语义清晰，便于运维与审计
  • 上线前校验 .htaccess 与前端 rewrite 开关一致性
  • 定期清理 storage/state 下临时文件，避免残留引导脚本