- inspect-webkit là CLI tool mới của Evan Bacon (Expo) cho phép debug Safari và WKWebView trên iOS trực tiếp từ Chrome DevTools hoặc VS Code - không cần Xcode, không cần native dependencies.
- Tool hỗ trợ 15 CDP domain, stubs ~80 lệnh để ngăn Safari bị đóng băng, và được viết bằng pure Bun/TypeScript.
- MIT license, chạy ngay với npx inspect-webkit.
TL;DR
Evan Bacon (Expo) vừa publish inspect-webkit - một CLI tool viết bằng pure Bun/TypeScript cho phép debug Safari và WKWebView trên iOS devices lẫn Simulator trực tiếp từ Chrome DevTools hoặc VS Code. Không cần Xcode menus. Không cần libimobiledevice. Không cần ios-webkit-debug-proxy. Chỉ một lệnh:
npx inspect-webkit
Vấn đề: debug Safari trên iOS vốn "hostile to anything programmatic"
Quy trình debug WKWebView truyền thống nghe thôi đã nản: mở Safari trên macOS, vào Preferences bật Develop menu, kết nối iPhone, chờ device xuất hiện, click qua host rồi app rồi mới đến page target. Fine nếu bạn là con người. Hostile hoàn toàn nếu bạn là AI agent hay CI pipeline.
Các công cụ cũ như ios-webkit-debug-proxy của Google (viết bằng C, cần build từ source, phụ thuộc libimobiledevice) hay remotedebug-ios-webkit-adapter của Microsoft (bị abandon từ lâu) đều không giải quyết được gap ngày càng lớn giữa Chrome DevTools Protocol (CDP) và WebKit Inspector Protocol. Kết quả: DevTools bị freeze, lệnh không phản hồi, developer bỏ cuộc.
Dưới nắp capô: bridge CDP sang WIR
inspect-webkit dựng một CDP endpoint tại localhost:9222. Mỗi iOS page (device hoặc simulator) xuất hiện như một CDP target. Phía sau, tool dịch tất cả request giữa Chrome DevTools Protocol và Safari's Web Inspector wire protocol (WIR) - protocol nội bộ của Apple với các key bắt đầu bằng WIR*.
Transport path phân theo loại target:
- iOS device: kết nối qua
usbmuxd, tunnel đếnlockdownd, upgrade TLS, rồi startcom.apple.webinspectorservice. - iOS Simulator: connect trực tiếp qua Unix socket của
webinspectord_sim- không TLS, không usbmux. - Desktop Safari: không hỗ trợ - Apple gate bằng private entitlement chỉ dành cho Safari signed của Apple.
Điểm đặc biệt: modern Chrome DevTools gửi ~70 commands khi attach, trong đó ~30 commands iOS không implement. Nếu forward bất kỳ command nào trong số đó đến Safari, inner page target sẽ bị wedge - toàn bộ inspector đóng băng im lặng. inspect-webkit stubs ~80 CDP-only entries ngay tại bridge layer, đảm bảo chúng không bao giờ reach Safari.
Bắt đầu trong 60 giây
Yêu cầu cơ bản:
- macOS host
- iOS device kết nối USB, đã trust máy tính
- Bật Settings > Safari > Advanced > Web Inspector trên iPhone
- Với WKWebView (iOS 16.4+): app phải set
webView.isInspectable = true
Chạy tool:
npx inspect-webkitMở Chrome, vào chrome://inspect/#devices, click Configure..., thêm localhost:9222. Vài giây sau iOS target xuất hiện trong "Remote Target". Click inspect - DevTools đính vào page, sẵn sàng debug như web thông thường.
Với VS Code, thêm launch configuration type chrome, attach đến port 9222, chọn page từ dropdown.
Debug tip: set INSPECT_WEBKIT_DEBUG=1 để trace lockdown/TLS/RPC handshake nếu cần troubleshoot kết nối.
15 CDP domain đã verify hoạt động
Tool ship với e2e probe cdp-domains.ts - khảo sát 51 method để verify coverage. Các domain đã confirm:
- Runtime: evaluate, getProperties, callFunctionOn -
debugger;statement pause đúng (bridge tự kicksetPauseOnDebuggerStatements) - DOM + CSS: full Styles panel, live edit CSS, DOM search, box model
- Network: cookie management, request lifecycle events, setCacheDisabled, setUserAgentOverride
- Debugger: breakpoints (kể cả
setBreakpointByUrl), stepping, scriptParsed - Accessibility, Overlay, Emulation, Input
Codebase chỉ dùng ~half the LOC so với remotedebug-ios-webkit-adapter của Microsoft, không có lodash, async-lock, hay EventEmitter.
So sánh với các công cụ trước
| Tool | Native deps | CDP compat | Trạng thái | Giá |
|---|---|---|---|---|
| ios-webkit-debug-proxy | C, libimobiledevice | Broken với Chrome mới | Duy trì, nhưng protocol lag | Free |
| remotedebug-ios-webkit-adapter | Cần proxy trên | Partial | Abandoned (Microsoft) | Free |
| inspect.dev CLI | None | Full | Active, commercial | Có phí |
| inspect-webkit | None | Full, ~80 stubs | Mới, Evan Bacon | MIT, free |
Những gì chưa hoạt động
Do Safari không expose một số tính năng qua WIR, các capability sau không khả dụng (và đây là Safari-side gap, không phải bridge bug):
Network.getResponseBody- Safari không expose response bodyPage.captureScreenshot- không có trong WIRPage.startScreencast- được accept nhưng không emit frames trên iOS 26Emulation.setDeviceMetricsOverride-Page.setScreenSizeOverridebị remove trong iOS 26- Desktop Safari - bị gated bởi Apple private entitlement
Dành cho ai nên thử ngay
Nếu bạn là web developer đang debug iOS-specific rendering bug mà không muốn context switch sang Safari, hoặc đang build CI pipeline cần programmatic access vào iOS browser targets, inspect-webkit là tool đáng thử nhất hiện tại trong ecosystem. Tool được viết explicitly for AI agents và CI - điều mà các giải pháp trước không bao giờ đặt làm mục tiêu đầu tiên.
Cũng đáng theo dõi: tool đang active development với daily commits từ Evan Bacon. Ecosystem Expo/React Native sẽ hưởng lợi lớn khi AI agent có thể programmatically debug WKWebView trong app.
