目录

SourceMap Splitter

Overview

After DevEco Studio completes compilation and building, it packages the SourceMap information of all source files within each module into an aggregated SourceMap file named sourceMaps.map. Since this file does not follow the standard SourceMap v3 format, standard tools such as Chrome DevTools and the source-map library cannot directly parse it, making it difficult for developers to reconstruct crash stacks and locate source code.

SourceMap Splitter is a command-line tool designed specifically for this scenario. It can quickly split the aggregated sourceMaps.map into independent .map files that conform to the SourceMap v3 specification, and automatically export them according to the source directory structure, making it easy to locate issues using the standard toolchain. This tool has zero external runtime dependencies. After downloading the single-file artifact split-sourcemaps.js from SourceMap Splitter, you can run it directly.

Environment Setup

Before using this tool, ensure that the runtime environment meets the following requirements:

Tool Specifications

This section describes the command format, parameters, input file paths, output directory rules, and exit codes of the tool.

[h2]Split Command

Reads the aggregated SourceMap files of one or more modules, splits them into independent .map files that conform to the SourceMap v3 specification, and outputs them according to the source directory structure. When multiple modules are specified, the split results are merged into the same output directory, with automatic cross-module deduplication. The command format is as follows:

node split-sourcemaps.js [--project <path>] [--module <name>] [--output <path>]

Parameter description:

Option Required Description
--project <path> No

Root directory of the HarmonyOS project.

If this parameter is not specified, it defaults to the current working directory.
--module <name> No

Module name. Multiple modules can be specified, either separated by commas (for example, entry,feature) or by repeating --module. Both methods are equivalent, and duplicates are automatically removed in the order of first occurrence. A single module name cannot be empty or ., cannot contain .. or path separators (/, \), and cannot be an absolute path.

If this parameter is not specified, it defaults to entry.
--output <path> No

Output directory for the split results. Both absolute and relative paths are supported.

If this parameter is not specified, it defaults to .split-sourcemaps.
--help, -h No Displays help information.

[h2]Input File Path

The tool searches for the aggregated SourceMap file generated by DevEco Studio during build in the following path:

{project}/{module}/build/default/outputs/default/mapping/sourceMaps.map

[h2]Output Directory Security Rules

To prevent accidental deletion of user data, the tool follows these rules when writing to the output directory:

[h2]Exit Codes

After the tool finishes execution, it returns an exit code that reflects the result of the current execution. You can use this exit code in scripts or CI pipelines to determine whether the split was successful.

Exit Code Description
0 Split successful.
1 An error occurred, for example, invalid arguments, the project directory or aggregate SourceMap file does not exist, JSON parsing failed, or the output directory is non-empty and was not created by this tool.

Usage Examples

[h2]Basic Usage

Splits the aggregated SourceMap file of the entry module, using the default output directory .split-sourcemaps.

node split-sourcemaps.js --project /path/to/project --module entry

[h2]Specifying the Output Directory

Uses --output to output the split result to a custom directory instead of the default .split-sourcemaps. This parameter supports both absolute and relative paths.

node split-sourcemaps.js --project /path/to/project --module entry --output ./sourcemap-output

[h2]Running Directly in the Project Root Directory

When --project is not specified, it defaults to the current directory; when --module is not specified, it defaults to entry. Therefore, the tool can be run directly in the project root directory.

node split-sourcemaps.js

[h2]Splitting Multiple Modules at Once

Specify multiple modules by separating them with commas or repeating --module. The two approaches are equivalent, and the split results are merged into the same output directory.

# The following two approaches are equivalent. Choose either one.
# Approach 1: comma-separated
node split-sourcemaps.js --project /path/to/project --module entry,feature,library
# Approach 2: pass --module repeatedly
node split-sourcemaps.js --project /path/to/project --module entry --module feature

Since the aggregated SourceMap file of modules such as entry typically contains source mappings of their dependent modules, duplicate entries pointing to the same source file may appear across different modules. The tool automatically performs deduplication in the order in which the modules are specified: the first occurrence of an entry is written, and subsequent entries pointing to the same output path are skipped. If a later module contains an entry with the same path but different content, the tool prints WARNING: potential version conflict ... to standard error as a hint, but does not interrupt the process and still uses the first occurrence as the final result.

In addition, if any specified module is missing its build artifacts, the tool lists all missing modules at once and exits with an error before writing any files, without corrupting the existing output directory.

[h2]Reference output

Upon a successful split, the standard output prints the number of split entries and the output directory:

Split 5/5 sourcemap entries to .split-sourcemaps

Here, 5/5 indicates that the aggregated SourceMap file contains five entries in total, and all of them are split successfully. If the path of some entries cannot be resolved or duplicates exist, the tool skips those entries and outputs a prompt to standard error, in which case the number of successful splits will be less than the total.

When splitting multiple modules at once, the standard output additionally prints the list of modules involved in the split. If cross-module deduplication occurs, the number of deduplicated entries is also printed:

Split 8/10 sourcemap entries to .split-sourcemaps
Modules: entry, feature
Deduplicated 2 cross-module path(s) (first module wins).

[h2]Output Structure Example

Assume that the input aggregated SourceMap file sourceMaps.map contains the following five entries:

sourceMaps.map
├── entry|entry|1.0.0|src/main/ets/pages/Index.ts
├── entry|entry|1.0.0|src/main/ets/entryability/EntryAbility.ts
├── entry|library|2.0.0|src/main/ets/components/MainPage.ts
├── entry|entry|1.0.0|generated/ets/routerMap.ts
└── entry|entry|1.0.0|src/main/ets/utils/Helper.no-sources.ts

After splitting, independent .map files are generated based on the module and source directory structure:

.split-sourcemaps/
├── entry/
│   ├── src/main/ets/pages/Index.ts.map
│   ├── src/main/ets/entryability/EntryAbility.ts.map
│   ├── generated/ets/routerMap.ts.map
│   └── src/main/ets/utils/Helper.no-sources.ts.map
└── library/
    └── src/main/ets/components/MainPage.ts.map

Output file naming rule: For each entry, the output file appends .map after the original extension of the source file name. For example, the source file Index.ts corresponds to Index.ts.map, and Helper.no-sources.ts corresponds to Helper.no-sources.ts.map. In other words, the original extension is preserved, and .map is appended at the end.

FAQs

[h2]Aggregated SourceMap File Not Found

Symptom

The tool reports an error: Aggregated sourcemap not found for ... module(s): ....

Possible Causes

The project has not been built yet, or the --project or --module arguments are incorrect, causing the aggregated SourceMap file to be missing from the path of one or more specified modules.

Solution

Build the modules using DevEco Studio first, and verify that --project points to the project root directory and --module specifies the correct module name.

[h2]Project Directory Does Not Exist

Symptom

The tool reports an error: Project directory does not exist: ....

Possible Causes

The directory specified by --project does not exist.

Solution

Verify that the --project argument points to a valid project root directory.

[h2]Invalid Module Name

Symptom

The tool reports Invalid module name: ... during execution.

Possible cause

The --module parameter is ., contains .., contains a path separator (/ or \), or is an absolute path. Invalid examples: ., .., my/module, /entry, C:\entry.

Resolution

Change --module to a valid module name that does not contain a path separator, for example, entry.

[h2]Output Directory Is Not Empty and Was Not Created by This Tool

Symptom

The tool reports an error during execution: Output directory is not empty and was not created by this tool: ....

Possible Causes

To prevent accidental deletion of user data, the tool refuses to clear directories that are not empty and were not created by this tool.

Solution

Manually delete the directory, or use --output to specify an empty directory or a directory dedicated to storing output.

[h2]Failed to Parse the Aggregated SourceMap File

Symptom

The tool reports an error: Failed to parse aggregated sourcemap: ... or Aggregated sourcemap must be a JSON object ....

Possible Causes

The aggregated SourceMap file content is not a valid JSON object. The file may be corrupted or truncated.

Solution

Rebuild the project using DevEco Studio to generate a complete aggregated SourceMap file.

[h2]Some Entries Skipped

Symptom

The split succeeds, but Skipping entry with unresolvable path ... or Skipping duplicate output path ... appears in stderr, and the reported split count is less than the total.

Possible Causes

The path of some entries cannot be resolved, or multiple entries map to the same output path after restoration. The tool skips these entries.

Solution

This is normal fault tolerance behavior of the tool. Skipped entries do not affect the split result of the remaining entries. To investigate specific entries, refer to the key information provided in stderr.