mod_vhost_alias 是 Apache 专为动态映射大量结构化子域名（如 user1.example.com）而设的模块，通过 VirtualDocumentRoot 等指令在运行时解析路径，避免硬编码数百个 VirtualHost 块导致的性能与维护问题。
mod_vhost_alias 是什么，为什么不用 VirtualHost 块硬编码
它不是用来替代传统 VirtualHost 的“高级版”，而是专为大量结构化域名（比如 user1.example.com、blog2.example.com）做自动映射的模块。硬写几百个 VirtualHost 块既难维护，又会让 Apache 启动变慢、内存占用高——mod_vhost_alias 把匹配逻辑交给运行时解析，配置只留一条规则。
启用前确认模块已加载：a2enmod vhost_alias（Debian/Ubuntu）或检查 httpd.conf 中有 LoadModule vhost_alias_module modules/mod_vhost_alias.so。
关键指令：VirtualDocumentRoot 和 VirtualScriptAlias 怎么配
这两个是核心，决定请求域名如何映射到文件系统路径。区别在于：VirtualDocumentRoot 控制静态资源根目录，VirtualScriptAlias 控制 CGI/PHP 脚本路径（如 php-cgi 处理器位置）。
-
%0表示完整主机名（foo.bar.example.com） -
%1表示第一个子域（foo），%2是第二个（bar），以此类推；%-1表示倒数第一个（即最右段，通常是com） - 路径中支持变量拼接，例如
/var/www/vhosts/%1/htdocs会把alice.example.com指向/var/www/vhosts/alice/htdocs - 如果域名含端口（如
test.example.com:8080），默认不包含端口；需用%{PORT}显式引用（仅部分 Apache 版本支持）
典型配置片段：
<virtualhost>
ServerName example.com
ServerAlias *.example.com
UseCanonicalName Off
VirtualDocumentRoot /var/www/vhosts/%1/htdocs
VirtualScriptAlias /var/www/vhosts/%1/cgi-bin
</virtualhost>
常见错误：403 Forbidden 或 404 Not Found 怎么排查
绝大多数问题出在路径解析结果不符合预期，而不是权限本身。先验证 Apache 实际解析出的路径：
- 开启
LogLevel info并查看 error log，Apache 会在请求日志里打印类似[info] [client x.x.x.x] VirtualDocumentRoot is now /var/www/vhosts/test/htdocs的行 - 确保目标目录存在且 Apache 用户（如
www-data或apache）有执行（x）权限进入父目录，有读（r）权限打开文件 -
VirtualDocumentRoot不支持.htaccess自动继承？错——只要AllowOverride在对应None即可，但注意该块必须显式声明（mod_vhost_alias不自动创建） - 如果用了
ServerAlias *.example.com却访问example.com本身，它不会命中——需单独加一个VirtualHost或用ServerAlias example.com补充
与 mod_rewrite 混用时要注意什么
可以共存，但顺序和目的要分清：mod_vhost_alias 解决“哪个目录”，mod_rewrite 解决“怎么路由内部 URL”。别试图用 rewrite 去“模拟”虚拟主机路径，那会绕过 VirtualDocumentRoot 的设计初衷，还容易引发循环重写。
- 若需对特定子域做特殊跳转（如把
old.example.com301 到new.example.com），应在独立的VirtualHost块里用RewriteRule，而非在通配块里加条件判断 -
RewriteCond %{HTTP_HOST}仍可用，但注意此时%{DOCUMENT_ROOT}已由mod_vhost_alias设定完毕，不要在 rewrite 中再手动拼路径 - 性能上，
mod_vhost_alias是 C 层直接查表，比每次进mod_rewrite解析快得多；高频场景下优先靠它解决路由
真正麻烦的是 DNS 解析延迟或泛域名证书覆盖不全——mod_vhost_alias 本身不处理 HTTPS，SNI 和证书仍得靠 VirtualHost + SSLCertificateFile 显式配置，动态虚拟主机基本只适用于 HTTP 场景或配合 ACME 自动续签工具链使用。
