目录

Nginx 配置指南

最后更新: 2026-01-27 11:02:47

Nginx 配置指南

本文档详细说明 Unicode Framework 在各种视图模式下的 Nginx 配置方法。

基础配置

基本服务器配置

server {
    listen 80;
    server_name example.com;
    root /path/to/framework/public;
    index index.php;

# 字符集设置
    charset utf-8;


# 日志配置
    access_log /var/log/nginx/example.com.access.log;
    error_log /var/log/nginx/example.com.error.log;


# 安全设置：隐藏 Nginx 版本
    server_tokens off;


# 禁止访问隐藏文件
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }


# PHP 处理
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        
        # 增加超时时间（用于长时间运行的请求）
        fastcgi_read_timeout 300;
        fastcgi_send_timeout 300;
    }
}

Smarty 模板引擎配置

Smarty 是框架的默认模板引擎，使用传统的服务端渲染方式。

完整配置示例

server {
    listen 80;
    server_name example.com;
    root /path/to/framework/public;
    index index.php;

# 静态资源缓存
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }


# 框架入口文件
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }


# PHP 处理
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }


# 禁止访问敏感目录
    location ~ ^/(vendor|storage|runtime|config|app|tests|docs|\.env) {
        deny all;
        return 404;
    }
}

Vue3 SPA 配置

Vue3 SPA（单页应用）模式需要特殊的路由处理，确保所有路由都指向 index.php，同时正确处理静态资源。

开发环境配置

开发环境需要同时处理：

  • PHP 后端 API
  • Vite 开发服务器（用于前端热更新）

    • server {
    listen 80;
    server_name example.com;
    root /path/to/framework/public;
    index index.php;

    # 静态资源（优先处理）
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
    

    # Vue SPA 构建后的静态资源
    location /js/ {
        alias /path/to/framework/public/js/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    

    # Vite 开发服务器代理（仅开发环境）
    location /js/admin/ {
        proxy_pass http://localhost:5173;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 支持（Vite HMR）
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
    

    # API 路由（代理到 PHP）
    location /admin/api {
        try_files $uri /index.php?$query_string;
    }
    

    # Vue SPA 路由 - 所有路由都指向 index.php
    location /admin {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # 其他路由
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # PHP 处理
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

    生产环境配置

    生产环境使用构建后的静态文件，不需要 Vite 开发服务器。

    server {
    listen 80;
    server_name example.com;
    root /path/to/framework/public;
    index index.php;

    # 静态资源缓存（包括 Vue 构建文件）
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot|map)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
    

    # Vue SPA 构建后的文件
    location /js/ {
        alias /path/to/framework/public/js/;
        expires 1y;
        add_header Cache-Control "public, immutable";
        
        # 支持 source map
        location ~* \.map$ {
            expires 1d;
            add_header Cache-Control "public";
        }
    }
    

    # Vue SPA 路由 - 所有路由都指向 index.php
    location /admin {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # API 路由
    location /admin/api {
        try_files $uri /index.php?$query_string;
    }
    

    # 其他路由
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # PHP 处理
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

    Vue3 SSR 配置

    Vue3 SSR（服务端渲染）模式需要 Node.js 服务器处理 SSR 渲染。

    完整配置示例

    <h1 id="上游-nodejs-ssr-服务器">上游 Node.js SSR 服务器</h1>
upstream nodejs_ssr {
    server 127.0.0.1:3000;
    keepalive 64;
}

    server {
    listen 80;
    server_name example.com;
    root /path/to/framework/public;
    index index.php;
    

    # 静态资源
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
    

    # SSR 路由 - 代理到 Node.js 服务器
    location /ssr {
        proxy_pass http://nodejs_ssr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    

    # API 路由
    location /api {
        try_files $uri /index.php?$query_string;
    }
    

    # 其他路由
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # PHP 处理
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

    多应用模式配置

    框架支持多应用模式，可以通过路径前缀区分不同应用（如 /admin、/api 等）。

    路径策略配置

    server {
    listen 80;
    server_name example.com;
    root /path/to/framework/public;
    index index.php;

    # 静态资源
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
    

    # Admin 应用（Vue SPA）
    location /admin {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # Admin API
    location /admin/api {
        try_files $uri /index.php?$query_string;
    }
    

    # Admin 静态资源
    location /js/admin {
        alias /path/to/framework/public/js/admin/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    

    # Index 应用
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # PHP 处理
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

    域名策略配置

    如果使用域名策略区分应用：

    <h1 id="admin-应用adminexamplecom">Admin 应用（admin.example.com）</h1>
server {
    listen 80;
    server_name admin.example.com;
    root /path/to/framework/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
    

    <h1 id="主应用wwwexamplecom">主应用（www.example.com）</h1>
server {
    listen 80;
    server_name www.example.com example.com;
    root /path/to/framework/public;
    index index.php;
    

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

    开发环境配置

    开发环境需要支持：

  • Vite 开发服务器（HMR 热更新）
  • PHP 后端 API
  • 实时重载

    • 完整开发环境配置

    server {
    listen 80;
    server_name localhost;
    root /path/to/framework/public;
    index index.php;

    # Vite 开发服务器代理（HMR 支持）
    location /js/admin/ {
        proxy_pass http://localhost:5173;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 支持（Vite HMR）
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
    

    # Vite HMR WebSocket
    location /ws {
        proxy_pass http://localhost:5173;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
    

    # 静态资源（开发环境不缓存）
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires -1;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }
    

    # API 路由
    location /admin/api {
        try_files $uri /index.php?$query_string;
    }
    

    # Vue SPA 路由
    location /admin {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # 其他路由
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # PHP 处理
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass 127.0.0.1:9000;  # 开发环境通常使用 TCP
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        
        # 开发环境允许更大的超时时间
        fastcgi_read_timeout 600;
        fastcgi_send_timeout 600;
    }
}

    生产环境优化

    性能优化配置

    server {
    listen 80;
    server_name example.com;
    root /path/to/framework/public;
    index index.php;

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml text/javascript 
               application/json application/javascript application/xml+rss 
               application/rss+xml font/truetype font/opentype 
               application/vnd.ms-fontobject image/svg+xml;
    

    # Brotli 压缩（如果已安装）
    # brotli on;
    # brotli_comp_level 6;
    # brotli_types text/plain text/css text/xml text/javascript 
    #              application/json application/javascript application/xml+rss;
    

    # 静态资源缓存
    location ~* \.(jpg|jpeg|png|gif|ico|webp|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
    

    location ~* \.(css|js)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
    

    location ~* \.(woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
        add_header Access-Control-Allow-Origin *;
    }
    

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    

    # 路由处理
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    # PHP 处理
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        
        # 缓存 FastCGI 响应
        fastcgi_cache_path /var/cache/nginx levels=1:2 keys_zone=php_cache:10m max_size=100m inactive=60m;
        fastcgi_cache php_cache;
        fastcgi_cache_valid 200 60m;
        fastcgi_cache_bypass $http_pragma $http_authorization;
        fastcgi_no_cache $http_pragma $http_authorization;
    }
}

    HTTPS 配置

    server {
    listen 80;
    server_name example.com;
    return 301 https://$server_name$request_uri;
}

    server {
    listen 443 ssl http2;
    server_name example.com;
    root /path/to/framework/public;
    index index.php;
    

    # SSL 证书配置
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    

    # HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    

    # 其他配置...
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

    常见问题

    1. Vue SPA 路由返回 404

    问题：访问 Vue SPA 路由时返回 404。 解决方案：确保所有路由都指向 index.php： 
    location /admin {
    try_files $uri $uri/ /index.php?$query_string;
}

    2. 静态资源无法加载

    问题：Vue 构建后的静态资源（JS、CSS）无法加载。 解决方案：检查静态资源路径配置： 
    location /js/ {
    alias /path/to/framework/public/js/;
    expires 1y;
    add_header Cache-Control "public, immutable";
}

    3. Vite HMR 不工作

    问题：开发环境下 Vite 热更新不工作。 解决方案：确保 WebSocket 代理配置正确： 
    location /js/admin/ {
    proxy_pass http://localhost:5173;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

    4. API 请求被缓存

    问题：API 响应被浏览器或 Nginx 缓存。 解决方案：为 API 路由禁用缓存： 
    location /admin/api {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Pragma "no-cache";
    add_header Expires "0";
    try_files $uri /index.php?$query_string;
}

    5. 文件上传大小限制

    问题：文件上传失败，提示文件过大。 解决方案：增加客户端和服务器端限制： 
    client_max_body_size 100M;

    location ~ \.php$ {
    # ...
    fastcgi_param PHP_VALUE "upload_max_filesize=100M \n post_max_size=100M";
}

    6. 多应用路由冲突

    问题：多应用模式下路由冲突。 解决方案：确保路由顺序正确，更具体的路由在前： 
    <h1 id="更具体的路由在前">更具体的路由在前</h1>
location /admin/api {
    try_files $uri /index.php?$query_string;
}

    location /admin {
    try_files $uri $uri/ /index.php?$query_string;
}
    

    location / {
    try_files $uri $uri/ /index.php?$query_string;
}

    配置检查清单

    部署前请检查：

  • [ ] 文档根目录指向 public 目录
  • [ ] PHP-FPM 配置正确
  • [ ] 静态资源路径正确
  • [ ] Vue SPA 路由配置正确
  • [ ] 开发环境 Vite 代理配置正确
  • [ ] 生产环境静态资源缓存配置正确
  • [ ] 安全头配置正确
  • [ ] Gzip 压缩已启用
  • [ ] HTTPS 配置正确（生产环境）
  • [ ] 文件上传大小限制已设置

    • 相关文档

  • 部署指南
  • Vue3 集成
  • 多应用模式
  • 视图系统

---

注意：配置完成后，请使用 nginx -t 测试配置文件的语法，然后使用 nginx -s reload 重新加载配置。