Skip to main content

Nginx Server Configuration

This guide describes how to deploy H5 applications on Nginx server and configure WeChat MiniProgram domain name verification file access.

Cloud Platform User Tip

If you use cloud platforms such as Baidu Cloud, Alibaba Cloud, Tencent Cloud, Huawei Cloud, etc., HTTPS certificates are usually automatically configured through the platform console. This document mainly focuses on H5 application deployment and WeChat verification file configuration.

Prerequisites​

  • Nginx installed (recommended version 1.18+)
  • Domain name has HTTPS certificate configured (usually automatically handled by cloud platforms)
  • WeChat domain name verification file downloaded (such as a1b2c3d4e5f6.txt)
  • H5 application built

Verification File Placement Options​

Based on your needs, you can choose one of the following two options:

Place the verification file directly in the H5 application's root directory, at the same level as index.html.

Directory Structure:

/var/www/h5/
├── a1b2c3d4e5f6.txt  ← Verification file (random filename generated by WeChat)
├── index.html
├── assets/
│   ├── js/
│   ├── css/
│   └── images/
└── ...

Advantages:

  • Simple configuration, no additional location rules needed
  • Suitable for most scenarios

Disadvantages:

  • Verification file mixed with business code

Option 2: Separate Directory​

Place the verification file in a dedicated directory, separate from the H5 application.

Directory Structure:

/var/www/weixin-verify/
└── a1b2c3d4e5f6.txt  ← Verification file (random filename generated by WeChat)

/var/www/h5/
├── index.html
├── assets/
└── ...

Advantages:

  • Clear structure, easy to manage verification files for multiple domains
  • Verification file separated from business code

Disadvantages:

  • Requires additional Nginx location rule configuration
Recommendation

If your H5 project itself doesn't have other .txt files, Option 1 is recommended for simpler configuration.

Nginx Configuration​

Option 1 Configuration (Verification file in project root directory)​

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name h5.example.com;

    # SSL certificate configuration (usually automatically managed by cloud platform)
    # If manual configuration is needed, uncomment the following two lines:
    # ssl_certificate /path/to/your/fullchain.pem;
    # ssl_certificate_key /path/to/your/privkey.pem;

    # H5 pages and verification files are in the same root directory
    location / {
        root /var/www/h5;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # Log configuration
    access_log /var/log/nginx/h5_access.log;
    error_log /var/log/nginx/h5_error.log;
}

# HTTP auto-redirect to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name h5.example.com;
    return 301 https://$server_name$request_uri;
}

Option 2 Configuration (Verification file stored separately)​

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name h5.example.com;

    # SSL certificate configuration (usually automatically managed by cloud platform)
    # If manual configuration is needed, uncomment the following two lines:
    # ssl_certificate /path/to/your/fullchain.pem;
    # ssl_certificate_key /path/to/your/privkey.pem;

    # WeChat verification file dedicated configuration
    # Matches all .txt files (WeChat verification filenames are random strings.txt)
    location ~ \.txt$ {
        root /var/www/weixin-verify;
        access_log off;  # No logging for verification file access
    }

    # H5 page configuration
    location / {
        root /var/www/h5;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # Log configuration
    access_log /var/log/nginx/h5_access.log;
    error_log /var/log/nginx/h5_error.log;
}

# HTTP auto-redirect to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name h5.example.com;
    return 301 https://$server_name$request_uri;
}
Warning

Option 2 configuration will direct all .txt file requests to /var/www/weixin-verify/. If your H5 project needs other .txt files, Option 1 is recommended or adjust the configuration.

Configuration Description​

Key Configuration Items​

Configuration ItemDescription
server_nameYour domain name, must match the domain name configured in WeChat backend
listen 443 sslHTTPS port configuration
rootStatic file root directory
try_filesURL rewrite rules, supports SPA routing
SSL Certificate Description

Cloud platforms (such as Baidu Cloud, Alibaba Cloud, Tencent Cloud) usually automatically inject SSL certificates into Nginx configuration after configuring them in the console.

Deployment Steps​

1. Create Directories​

# Option 1
sudo mkdir -p /var/www/h5

# Option 2
sudo mkdir -p /var/www/h5
sudo mkdir -p /var/www/weixin-verify

2. Upload Files​

# Upload H5 application files to server
# Use scp, rsync, or other tools

# Option 1: Place verification file in H5 root directory
sudo cp a1b2c3d4e5f6.txt /var/www/h5/

# Option 2: Place verification file in separate directory
sudo cp a1b2c3d4e5f6.txt /var/www/weixin-verify/

3. Set Permissions​

# Set file owner (adjust according to your Nginx configuration)
sudo chown -R nginx:nginx /var/www/h5
# Or
sudo chown -R www-data:www-data /var/www/h5

# Set file permissions
sudo find /var/www/h5 -type f -exec chmod 644 {} \;
sudo find /var/www/h5 -type d -exec chmod 755 {} \;

# Ensure verification file is readable
sudo chmod 644 /var/www/h5/a1b2c3d4e5f6.txt
# Or (Option 2)
sudo chmod 644 /var/www/weixin-verify/a1b2c3d4e5f6.txt

4. Create Nginx Configuration File​

# Create configuration file
sudo nano /etc/nginx/sites-available/h5.example.com.conf

# Paste the configuration content above into the file
# Save and exit (Ctrl+X, Y, Enter)

5. Enable Configuration​

# Create symbolic link
sudo ln -s /etc/nginx/sites-available/h5.example.com.conf /etc/nginx/sites-enabled/

# Test configuration syntax
sudo nginx -t

# If test passes, reload Nginx
sudo systemctl reload nginx

Verify Configuration​

Verify Verification File is Accessible​

# Test with curl (replace with actual filename)
curl https://h5.example.com/a1b2c3d4e5f6.txt

# View detailed response
curl -I https://h5.example.com/a1b2c3d4e5f6.txt

# Expected output:
# HTTP/2 200
# content-type: text/plain

Verify H5 Page is Accessible​

# Test homepage
curl -I https://h5.example.com

# Expected to return 200 status code

Verify HTTPS Redirect​

# Test if HTTP automatically redirects to HTTPS
curl -I http://h5.example.com

# Expected output:
# HTTP/1.1 301 Moved Permanently
# Location: https://h5.example.com/

Common Issues​

404 Error​

Cause: File path configuration error

Solution:

# Check if file exists
ls -la /var/www/h5/a1b2c3d4e5f6.txt

# Check root path in Nginx configuration
sudo nginx -T | grep root

403 Error​

Cause: File permission issue

Solution:

# Check file permissions
ls -la /var/www/h5/a1b2c3d4e5f6.txt

# Fix permissions
sudo chmod 644 /var/www/h5/a1b2c3d4e5f6.txt
sudo chown nginx:nginx /var/www/h5/a1b2c3d4e5f6.txt

500 Error​

Cause: Nginx configuration error

Solution:

# Check configuration syntax
sudo nginx -t

# View error logs
sudo tail -f /var/log/nginx/h5_error.log

Advanced Configuration​

Configure Multiple Domain Names​

server {
    listen 443 ssl http2;
    server_name h5.example.com h5-backup.example.com;

    # Other configuration...
}

Configure Reverse Proxy (API Forwarding)​

# Forward API requests to backend server
location /api {
    proxy_pass http://backend-server:8080;
    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;
}