Skip to main content

Troubleshooting

This guide provides troubleshooting solutions for common issues encountered when embedding H5 in Mini Programs.

Verification File Access Failed​

Problem Description​

WeChat backend prompts: "Unable to access verification file, please check if file is uploaded to domain root directory"

Troubleshooting Steps​

1. Browser Access Test​

Access in browser (replace with your actual filename):

https://h5.example.com/a1b2c3d4e5f6.txt

Determine the problem based on the return result:

  • Returns 404: File path configuration error
  • Returns 403: File permission issue
  • Returns 500: Server configuration error
  • Returns 200: Server configuration correct, may be WeChat server cache issue

2. Check Server Configuration​

Nginx Configuration Check:

# Test Nginx configuration syntax
sudo nginx -t

# View .txt file configuration in config file
cat /etc/nginx/sites-available/h5.example.com.conf | grep -A 5 "\.txt"

Confirm location and root paths are configured correctly.

Node.js Configuration Check:

Check static file middleware configuration order and paths:

// Ensure verification file route comes before other routes
app.use('/*.txt', express.static(path.join(__dirname, 'weixin-verify')));
app.use(express.static(path.join(__dirname, 'public')));

3. Check File Permissions​

# View file permissions (Option 1: file in H5 root directory)
ls -la /var/www/h5/*.txt

# Or (Option 2: file in separate directory)
ls -la /var/www/weixin-verify/*.txt

# Expected output:
# -rw-r--r-- 1 nginx nginx 32 Jan 17 10:00 a1b2c3d4e5f6.txt

# If permissions are wrong, fix permissions (based on actual filename and path)
sudo chmod 644 /var/www/h5/a1b2c3d4e5f6.txt
sudo chown nginx:nginx /var/www/h5/a1b2c3d4e5f6.txt
Tip

File permissions should be 644 (owner can read/write, others read-only), owner should be the web server user (like nginx, www-data, etc.).

4. Check File Path​

# Confirm file exists (based on your chosen option)
ls /var/www/h5/*.txt
# Or
ls /var/www/weixin-verify/*.txt

# Confirm file content is correct (do not modify WeChat-generated content)
cat /var/www/h5/a1b2c3d4e5f6.txt  # Replace with actual filename

5. Use curl for Detailed Testing​

# Detailed HTTPS access test
curl -v https://h5.example.com/a1b2c3d4e5f6.txt

# Expected output should include:
# < HTTP/2 200
# < content-type: text/plain
#
# [File content: random string]

Solution Summary​

IssueSolution
404 ErrorCheck file path and Nginx/Node.js configuration
403 ErrorFix file permissions to 644
500 ErrorCheck server configuration syntax
HTTPS Certificate IssueCheck if SSL certificate is valid
WeChat CacheWait a few minutes and retry, or test with different domain

WebView White Screen Issue​

Problem Description​

WebView component in Mini Program displays blank, unable to load H5 page.

Troubleshooting Steps​

1. Confirm Domain is Configured​

  • Login to WeChat Official Accounts Platform
  • Check if "Business Domains" list contains your domain
  • Confirm domain verification status is "Verified"

2. Confirm HTTPS is Accessible​

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

# Expected 200 status code
# HTTP/2 200

Access in regular browser to confirm page opens normally.

3. Check H5 Page Itself​

Test in Mobile Browser:

  1. Open H5 page in mobile browser (not WeChat)
  2. Check if page displays normally
  3. Check for JavaScript errors
  4. Check if resources fail to load (CSS, JS, images, etc.)

Common Issues:

  • Resources use relative paths, fail to load in WebView
  • Use of incompatible JavaScript APIs
  • CORS cross-origin issues

4. View Mini Program Console​

Add error listener in Mini Program:

// Mini Program page JS
Page({
    onLoad() {
        wx.onError((error) => {
            console.error('Mini Program error:', error);
        });
    }
});

View error information in WeChat Developer Tools console.

5. Real Device Debugging​

  1. Use "Real Device Debugging" feature in WeChat Developer Tools
  2. View specific error information on real device
  3. Check if network requests are intercepted

Common Causes and Solutions​

CauseSolution
Domain not configuredConfigure business domain in WeChat Official Accounts Platform
Invalid HTTPS certificateCheck and update SSL certificate
H5 page errorsDebug and fix in browser
Resource loading failureUse absolute paths or check CORS configuration
WebView compatibilityCheck if APIs used are compatible

Voice Function Not Working​

Cause:

WebRTC requires microphone permission, may be restricted in Mini Program WebView.

Solution:

  1. Ensure H5 page uses HTTPS

  2. Refer to FAQ - Microphone Permission Handling

Debugging Tips​

Enable vconsole​

Add vConsole to H5 for mobile debugging:

<script src="https://unpkg.com/vconsole@latest/dist/vconsole.min.js"></script>
<script>
    // Only enable in Mini Program environment
    wx.miniProgram.getEnv((res) => {
        if (res.miniprogram) {
            new VConsole();
        }
    });
</script>

Real Device Debugging Logs​

// Add detailed logs
console.log('[Debug] WebView loaded');
console.log('[Debug] User Agent:', navigator.userAgent);
console.log('[Debug] Window size:', window.innerWidth, window.innerHeight);

// Monitor errors
window.addEventListener('error', (e) => {
    console.error('[Error]', e.message, e.filename, e.lineno);
});

Mini Program Debugging​

// Mini Program page debugging
Page({
    onLoad() {
        console.log('[Debug] WebView page loaded');
    },

    handleMessage(e) {
        console.log('[Debug] Message from H5:', JSON.stringify(e.detail.data));
    }
});

Get Help​

If the above methods cannot solve your problem:

  1. Check console error logs
  2. Enable debug mode for detailed information
  3. Contact technical support team

Official Documentation: