iOS Safari Real-Device Debugging Pitfalls and HSTS Solutions

AI Summary · Perspective of a Serial Entrepreneur(Extracted by AI; viewpoints belong to the original author. You don't need to read the full article.)

Five typical Safari mobile debugging pitfalls in H5 development, along with fixes: 1. LAN IP cross-origin issues can be solved with a subdomain plus a router hosts entry. 2. iOS HSTS forces HTTPS redirects; clear Safari website data to resolve. 3. Blank dev tools or lost login state can be fixed by manually setting cookies in the console. 4. Page crashes may stem from an oversized bundle (e.g., 100MB); commenting out desktop code trims size significantly. 5. aspect-ratio doesn't work on button; use a div instead.

• Cross-origin LAN debugging: use a subdomain (local.paul.
• Safari HSTS enforcement: clear all website data for that domain in Safari settings to remove HSTS cache.
• Login state lost on real device: set cookies directly in Safari's console and set the domain to your debug host.
• Page crashes on mobile: check JS bundle size. Commenting out unused desktop route code trims the bundle quickly.
• aspect-ratio trap: button elements don't support aspect-ratio; switch to div.

Key Takeaways

The core pain points when debugging H5 pages on Safari real devices are network protocol restrictions (HSTS forcing HTTPS) and device performance limits (crashes from large JS bundles).

Solutions: 1. Use a subdomain plus router hosts instead of a LAN IP to fix cross-origin. 2. Clear Safari website data to remove HSTS cache. 3. Comment out desktop code to physically shrink the bundle. 4. Don't use aspect-ratio on button; use div instead.

1. Network Layer: Upgrade from LAN IP to Subdomain

Debugging directly via LAN IP often triggers backend API cross-origin errors. The standard fix is to create a subdomain sharing the same root as production and point it to your dev machine in the router's hosts file.

• Approach: If your production domain is paul.me, set your dev domain to local.paul.me and force-resolve it to your local IP in the router's hosts.
• Prerequisite: The backend must allow cross-origin requests from that subdomain.
• Benefit: Keeps your existing login-state passing logic intact and avoids auth failures caused by domain mismatch.
• Pitfall: If the page won't load but ping works, try reconnecting the Mac to the network and retry.

2. Protocol Layer: Bypass Safari HSTS Redirects

Local HTTP servers are often forced into a 307 redirect to HTTPS in iPhone Safari because HSTS cache is active. If you've previously visited the HTTPS version of the same root domain (e.g., paul.me), Safari remembers that policy and extends it to subdomains.

• Fix: Open iPhone Safari settings → find the target domain → tap "Clear Website Data" (this also clears login state) → revisit the page.
• Note: This deletes all cookies and cache for that domain. You'll need to log back in after debugging.

3. Runtime Layer: Fix Crashes and Lost Login State

1. Login state失效
Cookies set manually during Safari console debugging may fail due to domain or path mismatch.
Fix: When setting document.cookie in the console, explicitly specify domain=local.paul.me and path=/ so subsequent requests carry the correct cookie.

2. Page crash
One page had a bundle size of over 100MB and crashed directly on an iPhone 13. The root cause was shared Next.js routes between mobile and desktop, which bundled desktop-only code (including lots of unused logic) into the mobile build.

• Fix: Comment out the desktop-only route blocks. Tree shaking removes them automatically, dropping the JS bundle from 100MB to 2MB and restoring normal performance.
• Next step: Use dynamic imports or lazy-loaded routes to further isolate mobile and desktop code.

4. Style Layer: button Doesn't Support aspect-ratio

Applying aspect-ratio: 1/1 to a div inside a button causes the element to collapse because the button's default appearance style interferes.

• Fix: Replace the outer button with a div, or remove the default button style override (e.g., set appearance: auto).
• Verification: Be cautious with AI-generated code. CSS compatibility issues like this must be tested on real devices.

Original post · Paul's Xiaoyuzhou: Read original →