Upload SourceMap during project build process¶
Guance currently provides a webpack plugin that easily uploads SourceMap files from the corresponding directory during the Web project build process. This solves the cumbersome manual upload process.
Note: Currently supports uploads for Web applications.
Preparation¶
- Obtain the
OpenApidomain address for the corresponding site. - In Guance, obtain the
API KEYrequired for the correspondingOpenApi. - On the Guance platform, obtain the
applicationId,env, andversioninformation for the Web application. If there is no application, you need to create a new application. - Preparation is complete.
Webpack¶
Install @cloudcare/webpack-plugin
Modify the plugins option in the webpack.config.js file
// ....
const { SourceMapUploadWebpackPlugin } = require("@cloudcare/webpack-plugin")
module.exports = ({ mode }) => ({
//.....
devtool: "hidden-source-map",
plugins: [
//.....
new SourceMapUploadWebpackPlugin({
applicationId: "xxxxx", // Guance application appid
apiKey: "xxxxxxxx", // open apikey
server: "https://console.xxx-xxx.cn",
filepaths: ["dist/"], // Directories to search, can be files or directories
logLevel: "verbose", // Log printing level, optional
root: "dist/", // Set the directory for calculating relative paths, optional
env: "production", // Guance application env, optional
version: "1.0.0", // Guance application version, optional
}),
],
})
SourceMap WebpackPlugin Configuration Description¶
interface Options {
/**
*
* Files/directories to search for sourcemaps.
* All files matching the "extensions configuration" list but not matching the "ignore configuration" will be searched
* for sourcemap JSON or `//#sourceMappingURL=` comments to find generated file + source map pairs, then the source maps will be uploaded.
*/
filepaths: Array<string> | string
/**
* openApi Key generated by the Guance platform, generation method reference (https://docs.guance.com/en/management/api-key/open-api/#_1)
*/
apiKey: string
/**
* Guance platform OpenAPi service
*/
server: string
/**
* Guance RUM application corresponding applicationId (required)
*/
applicationId: string
/**
* Guance RUM application corresponding version (optional)
*/
version?: string
/**
* Guance RUM application corresponding env (optional)
*/
env?: string
/**
* Find all files that meet the conditions, but do not upload files, can be used for debugging
*/
dryRun?: boolean
/**
* Delete all found source map files after upload.
*/
deleteAfterUpload?: boolean
/**
* If source maps cannot be matched to their generated files via their sourceMappingURL, try matching by filename on the local disk
*/
matchSourcemapsByFilename: ?boolean
/**
* List of file extensions to look for in the directory
* Default [".js", ".map"].
*/
extensions?: Array<string>
/**
* List of files to ignore
*/
ignore?: Array<string>
/**
* Set the directory for calculating relative paths. The relative path of the uploaded sourcemaps should be included in the path that produces the error, therefore
* the meaning of this parameter is to control the relative directory of the upload
* Default relative path from execution directory to search directory path.relative(process.cwd(), filepath)
*/
root?: string
/**
* Used during debugging, the level of logs generated
*/
logLevel?: "quiet" | "normal" | "verbose"
/**
* Whether to ignore errors when execution fails. This configuration ensures that errors do not interrupt the compilation process. Default false, meaning errors are normally thrown by default
*/
warnOnFailure?: boolean
}
SourceMap Visibility in Production Environment¶
In production environments, SourceMap files are typically not retained for security reasons. These files allow developers to map minified or compiled code back to the original source code, but if made public, they could expose the application's internal logic, increasing security risks.
To handle SourceMaps safely, you can enable the deleteAfterUpload: true option when configuring the SourceMapUploadWebpackPlugin. This ensures that once SourceMaps are uploaded to the server, they are immediately deleted from the local file system, preventing them from being left behind in the production environment.
Additionally, by setting Webpack's devtool to "hidden-source-map", you can generate SourceMaps without including any references to them in the JavaScript files. This prevents browsers from attempting to download and view the source code.
If "hidden-source-map" is enabled, you should also set matchSourcemapsByFilename: true in the SourceMapUploadWebpackPlugin plugin. This configuration ensures the plugin can identify and upload the corresponding SourceMap files based on the JavaScript file names, even if there are no explicit references to them in the generated code.
Through these measures, you can effectively protect the security of the source code while maintaining the convenience of application debugging.
const { SourceMapUploadWebpackPlugin } = require('@cloudcare/webpack-plugin')
= require('@cloudcare/webpack-plugin')
module.exports = {
// Ensure that Webpack has been configured to output sourcemaps,
// but without the `sourceMappingURL` references in buidl artifacts.
devtool: 'hidden-source-map',
// ...
plugins: [
// Enable our plugin to upload the sourcemaps once the build has completed.
// This assumes NODE_ENV is how you distinguish production builds. If that
// is not the case for you, you will have to tweak this logic.
process.env.NODE_ENV === 'production'
? [
new SourceMapUploadWebpackPlugin({
...
deleteAfterUpload: true,
matchSourcemapsByFilename: true,
}),
]
: [],
],
}
How to DEBUG¶
If the corresponding SourceMap is not found during the running process, you can set the environment variable DEBUG=sourcemap-upload or configure logLevel: verbose and run the build command to view the specific running logs.
Notes¶
node version > 10.13, webpack version > 4¶
filepaths and root configuration notes:¶
-
There is an error in the Guance console, one line of which is
at SVGGElement.<anonymous> @ http://localhost:8000/js/chunk-vendors.732b3b98.js:1:93427 -
The relative path of the file that caused the error is
js/chunk-vendors.732b3b98.js -
If the js files are in the server's static directory as
dist/js/*.jsdist/js/*.js.map -
Plugin configuration
filepaths: ['dist'] -
Without configuring
root, the default value isdist/. The sourcemap file path uploaded to the Guance server would bedist/js/**.js.map -
In this case, a mismatch occurs between the uploaded file directory path and the path that generated the error. Therefore, you should add the configuration
root:'/'orroot: ''to ensure the uploaded directory path isjs/**.js.map.