English | 简体中文
A Web Remote Debug Toolkit.
The toolkit has two parts which are an SDK and a DevTools service. Firstly, deploy the DevTools service:
$ npx mprdev -h 0.0.0.0 -p 8090
# terminal will output a log as "DevTools: http://0.0.0.0:8090/remote_dev" which is the DevTools service backend entry
# asume that the WAN IP of the server is 123.123.123.123, then the DevTools service is served at 123.123.123.123:8090After deployment, in order to debug remotely, your web pages have to import SDK and connect to the DevTools service.
We highly recommend you to import the SDK from CDN at the very beginning of your web pages, which ensures the SDK logging all information of the pages. And the SDK will mount at global like window.RemoteDevSdk by default to export all APIs. After importing the SDK, if the DevTools service is deployed to 123.123.123.123:8090, the SDK is required to connect by passing the service info to a init method:
<script src="https://unpkg.com/mprdev"></script>
<script>RemoteSdkDev.init({ host: '123.123.123.123', port: 8090 })</script>Finally, open your web pages and the DevTools serve to enjoy your debugging journey.
Besides, if your web pages can't directly connect to the DevTools service, for example, the server is located at LAN, you need to proxy paths below:
- Path "/target" via WebSocket, to ensure the SDK connecting to the DevTools service.
- Path "/devtool" via WebSocket, to ensure the DevTools connecting to the DevTools service.
- Path "/remote_dev" via HTTPS/HTTP, to serve the DevTools service backend entry.
Currently, we implement a breakpoint feature based on vDebugger. So, besides the steps of "Getting Started" above, you have to do more for breakpoint debug. The SDK has to take over the execution of JavaScript.
Normally, just replacing the attribute type of <script> with text/mprdev will work. Both text/javascript and module are suitable:
<script src="/test.js"></script>
<script type="module" src="/module.js"></script>
<script type="text/javascript">console.log(1)</script>Replace with:
<script type="text/mprdev" src="/test.js"></script>
<script type="text/mprdev" src="/module.js"></script>
<script type="text/mprdev">console.log(1)</script>If the above way is unable to meet the requestment, two more APIs are offered for inputing the JavaScript source code of your web pages:
function debug(script: string, url: string): void // input source code for remote breakpoint debug
function debugSrc(scriptSrc: string): void // input source url for remote breakpoint debug-
The
debugmethod accepts two arguments, which are the source codescriptand the correspondingurl. Theurlargument is used to identify thescript, in order to match the breakpoint mapping in the DevTools service. -
The
debugSrcmethod accepts only one argument, which is the source urlscriptSrc. It has the same meaning of theurlof thedebugmethod, but this method will use it to request the source code for breakpoing debug.
For example, asume that a web page request the link below to import a script:
<script src="/test.js"></script>In order to take over execution of the script by the SDK, you can modify the page HTML and replace the <script> by the debugSrc method:
<script>RemoteDevSdk.debugSrc('/test.js')</script>
<!-- Equivalent to <script type="text/mprdev" src="/test.js"></script> -->Beware that, after taking over by the type="text/mprdev" attribute or the debugSrc method, loading scripts won't block the page render, which means adding defer to the original <script> like:
<script defer src="/test.js"></script>If script defer can't be accepted, or modifing the page HTML isn't allowed, you can use the debug method to wrap source codes before server responses. However, keep in mind to escape codes to ensure the codes are valid JavaScript string. Take Express as an example:
app.use('/test.js', (req, res) => {
res.send(`RemoteDevSdk.debug(\`${script.replace(/(`|\$|\\)/g, '\\$1')}\`, '${req.url}');`);
});Be attention to keep the format as below when wrapping codes by the debug method, because the DevTools service will match and filter the wrapper strictly to make sure the source codes can be highlighted as expected:
// keep the wrapper format strictly as below ("%code%" is script string and "%url%" is script url)
RemoteDevSdk.debug(`%code%`, '%url%');
// DevTools service will replace the wrapper as below to ensure scripts can be highlighted
script.replace(/RemoteDevSdk\.debug\(`([\s\S]+)`,?.*\);?/, (_, code) => code.replace(/\\`/g, '`').replace(/\\\$/g, '$'));declare interface InitOptions {
host?: string | string[] // DevTools service deploy Host/IP (If receiving a host list, try sequently until connect succeeds)
port?: number // DevTools service deploy port
uin?: number // user id for display and search in Devtools service
title?: string // page title for display and search in Devtools service
protocol?: 'wss:' | 'ws:' // specify WebSocket protocol
}
export declare const version: string
export declare function init(opts: InitOptions): void
export declare function debug(script: string, url: string): void // input source code for remote breakpoint debug
export declare function debugSrc(scriptSrc: string): void // input source url for remote breakpoint debug
export declare function debugCache(check: boolean | ((url: string) => boolean)): void // control whether cache debug codes by url, which can reduce loading time
export declare function getId(): string // get device id
declare const RemoteDevSdk: {
version: typeof version
init: typeof init
debug: typeof debug
debugSrc: typeof debugSrc
debugCache: typeof debugCache
getId: typeof getId
}
export default RemoteDevSdk
declare global {
interface Window {
RemoteDevSdk: typeof RemoteDevSdk
}
}DevTools service backend entry supports different languages by appending url query lang:
# Chinese: http://0.0.0.0:8090/remote_dev?lang=cn (Default)
# English: http://0.0.0.0:8090/remote_dev?lang=engit clone https://github.com/wechatjs/mprdev
cd mprdev
npm install
npm run dev & npm start
# Test Page: http://localhost:8090/remote_dev/test
# DevTools Entry: http://localhost:8090/remote_dev