Nginx · PHP-FPM · Typecho

Nginx + PHP-FPM
部署 Typecho 完整指南

Q: Nginx 跑 PHP 为什么一定要 fastcgi_pass？

Nginx 本身不解析 PHP，只负责 HTTP 层请求。收到 .php 请求后，通过 fastcgi_pass 把请求转发给 PHP-FPM 进程，由 PHP-FPM 执行 PHP 脚本并返回结果。这是经典的 Nginx + PHP-FPM 架构。

Q: Typecho 的伪静态规则怎么写？

在 Nginx server 块里加 location /，内部重写到 index.php。Typecho 官方推荐的写法是：location / { if (!-e $request_filename) { rewrite ^(.*)$ /index.php$1 last; } }。

Q: Nginx 出现 502 Bad Gateway 怎么排查？

502 表示 Nginx 连不上 PHP-FPM。先看 PHP-FPM 是否在跑（ps aux | grep php-fpm），再看 Nginx 配置里 fastcgi_pass 的地址与 PHP-FPM 监听地址是否一致（127.0.0.1:9000 或 unix socket 路径），最后看 Nginx error.log 具体错误。

server 块怎么写、fastcgi 参数怎么传、伪静态怎么配、502/500 怎么查。附一套可直接抄的 Nginx 配置片段。

fastcgi_passNginx → PHP-FPM 的桥

HTTP_HOST不能漏的环境变量

rewriteTypecho 伪静态核心

502/500本文都有排查思路

TL;DR · 核心结论

Nginx 本身不执行 PHP，它通过 fastcgi_pass 把请求转发给 PHP-FPM 进程池。部署 Typecho 的核心是三件事：① Nginx server 块里 root 指向 Typecho 目录，index 加上 index.php；② location ~ \.php$ 块里 fastcgi_pass 到 PHP-FPM（TCP 127.0.0.1:9000 或 unix socket），include fastcgi_params，并显式设置 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name；③ 加 location / 把不存在的路径重写到 index.php 实现伪静态。502 基本都是 PHP-FPM 没跑或 fastcgi_pass 地址写错；500 多半是缺 PHP 扩展（如 tokenizer/mbstring）或文件权限不对。

Architecture

Nginx + PHP-FPM 的工作流程

一次请求在两个进程间怎么走

1. Nginx 接收请求 HTTP 层

Nginx 监听 80/443，按 server_name 和 URL 路径匹配 location。静态文件直接返回，PHP 文件转给 PHP-FPM。

2. fastcgi_pass 转发 FastCGI 协议

Nginx 把 HTTP 请求转成 FastCGI 协议包，发给 PHP-FPM 监听的 TCP 端口或 unix socket。见 ngx_http_fastcgi_module 文档。

3. PHP-FPM 执行进程池

PHP-FPM master 进程拉起 worker，worker 执行 SCRIPT_FILENAME 指定的 PHP 脚本，把输出通过 FastCGI 返回给 Nginx。

4. Nginx 返回客户端组装响应

Nginx 加上 HTTP 头、gzip、缓存控制，把结果发给浏览器。PHP 错误由 PHP-FPM 写入日志，Nginx 只能看到 5xx。

Nginx Config

可直接抄的 server 块

把 example.com 换成你的域名，root 换成 Typecho 实际目录

# /etc/nginx/http.d/typecho.conf（Alpine）或 sites-available/（Debian）
server {
    listen       80;
    server_name  example.com;
    root         /var/www/typecho;
    index        index.php index.html;

    # 伪静态：不存在的路径交给 index.php 处理
    location / {
        try_files $uri $uri/ /index.php$args;
    }

    # PHP 转发给 PHP-FPM
    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;   # 或 unix:/run/php83-fpm.sock;
        fastcgi_index  index.php;
        include        fastcgi_params;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
        fastcgi_param  HTTP_HOST        $host;
    }

    # 禁止访问敏感文件
    location ~ /\.     { deny all; }
    location ~* \.(db|sqlite|sql|log)$ { deny all; }
}

关键参数解释：$document_root 来自 ngx_http_core_module，见官方文档；SCRIPT_FILENAME 必须指向真实文件路径，PHP-FPM 靠它找到要执行的脚本。

PHP-FPM

PHP-FPM 配置要点

监听方式、进程数、用户权限

配置项	推荐值	说明
`listen`	`127.0.0.1:9000` 或 unix socket	unix socket 更快、不占端口，Nginx 同机部署时推荐
`user / group`	`nginx / nginx`（或 www-data）	PHP-FPM worker 以该用户身份读文件，必须能读 Typecho 目录
`pm`	`dynamic`	动态进程数，小内存机器省资源
`pm.max_children`	5~10（1G 内存）	按每个 worker 约 30~50 MB 估算
`pm.start_servers`	2~4	启动时拉起的进程数
`php_admin_value[error_log]`	`/var/log/php-fpm/error.log`	PHP 错误日志，500 排查必看

完整配置项见 PHP 官方 php-fpm 配置文档。

Pretty URL

Typecho 伪静态怎么配

让文章 URL 从 ?cid=1 变成 /archives/1/

1. Nginx 层伪静态

在 server 块加 location / { try_files $uri $uri/ /index.php$args; }
原理：真实存在的文件直接返回；不存在的路径全部交给 index.php，由 Typecho 路由
也可以用 if (!-e $request_filename) { rewrite ^(.*)$ /index.php$1 last; }

2. Typecho 后台设置

登录后台 → 设置 → 永久链接
选 "文章规则"，建议用 /archives/[cid]/
保存后首页、文章页、分类页 URL 都会变干净

3. 验证

访问 https://example.com/archives/1/ 应正常打开文章
访问一个不存在的路径应走 Typecho 的 404 页面，而不是 Nginx 默认 404
如果 404，多半是 try_files 没生效或 Nginx 配置没 reload

Debug

502 / 500 错误排查思路

按顺序查，90% 的问题能定位

现象	最可能原因	排查命令/位置
502 Bad Gateway	PHP-FPM 没跑，或 fastcgi_pass 地址与 PHP-FPM 监听地址不一致	`ps aux \| grep php-fpm`；看 Nginx error.log；对比 `listen` 配置
502 + connect() refused	Nginx 配置 `127.0.0.1:9000` 但 PHP-FPM 监听的是 unix socket	改 fastcgi_pass 为对应 socket 路径，或改 PHP-FPM listen 为 TCP
500 Internal Server Error	PHP 代码抛异常；常见是缺 php-tokenizer / php-mbstring 扩展	看 PHP-FPM error.log（见上表路径）；Alpine 上 `apk add php83-tokenizer php83-mbstring`
404 on 伪静态 URL	try_files / rewrite 没生效，或 Nginx 配置没 reload	`nginx -t && nginx -s reload`；确认 location / 块存在
CSS/JS 404	root 路径不对，或 HTTP_HOST 没传给 PHP，Typecho 生成了错误 URL	确认 `fastcgi_param HTTP_HOST $host;`；浏览器 F12 看静态文件 URL
403 Forbidden	Typecho 目录权限不对，PHP-FPM 用户读不到文件	`chown -R nginx:nginx /var/www/typecho`；目录至少 755，文件 644

FAQ

常见问题

Nginx 跑 PHP 为什么一定要 fastcgi_pass？+

Nginx 本身不解析 PHP，只负责 HTTP 层请求。收到 .php 请求后，通过 fastcgi_pass 把请求转发给 PHP-FPM 进程，由 PHP-FPM 执行 PHP 脚本并返回结果。这是经典的 Nginx + PHP-FPM 架构。

Typecho 的伪静态规则怎么写？+

在 Nginx server 块里加 location / { try_files $uri $uri/ /index.php$args; }，把不存在的路径内部重写到 index.php，由 Typecho 路由。也可以用 if (!-e $request_filename) { rewrite ^(.*)$ /index.php$1 last; }。

Nginx 出现 502 Bad Gateway 怎么排查？+

502 表示 Nginx 连不上 PHP-FPM。先看 PHP-FPM 是否在跑（ps aux | grep php-fpm），再看 Nginx 配置里 fastcgi_pass 的地址与 PHP-FPM 监听地址是否一致（127.0.0.1:9000 或 unix socket 路径），最后看 Nginx error.log 具体错误。

fastcgi_param HTTP_HOST 为什么不能漏？+

HTTP_HOST 告诉 PHP 当前访问的域名，Typecho 用它生成页面链接、判断后台地址。漏了会导致网站 CSS 加载不到、后台跳转错误、文章链接 404。标准 fastcgi_params 配置里必须包含这一项。

References

参考来源

Nginx 官方文档 — ngx_http_fastcgi_module：https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html
Nginx 官方文档 — ngx_http_core_module（$document_root 等变量）：https://nginx.org/en/docs/http/ngx_http_core_module.html
PHP 官方文档 — FastCGI Process Manager 配置：https://www.php.net/manual/en/install.fpm.configuration.php
Typecho 官方文档 — 安装指南：https://docs.typecho.org/install
Typecho 官方文档 — 常见问题：https://docs.typecho.org/faq

Nginx + PHP-FPM部署 Typecho 完整指南