API Reference

假如是通过NPM安装的，你可以在你的应用中这样加载UglifyJS：

  1. var UglifyJS = require("uglify-js");

这输出一个高级函数minify(code, options)，它能根据配置，实现多种最小化（即压缩、混淆等）。 minify()默认启用压缩和混淆选项。例子：

  1. var code = "function add(first, second) { return first + second; }";
  2. var result = UglifyJS.minify(code);
  3. console.log(result.error); // runtime error, or `undefined` if no error
  4. console.log(result.code);  // minified output: function add(n,d){return n+d}

你可以通过一个对象（key为文件名，value为代码）来同时最小化多个文件：

  1. var code = {
  2.     "file1.js": "function add(first, second) { return first + second; }",
  3.     "file2.js": "console.log(add(1 + 2, 3 + 4));"
  4. };
  5. var result = UglifyJS.minify(code);
  6. console.log(result.code);
  7. // function add(d,n){return d+n}console.log(add(3,7));

toplevel选项例子：

  1. var code = {
  2.     "file1.js": "function add(first, second) { return first + second; }",
  3.     "file2.js": "console.log(add(1 + 2, 3 + 4));"
  4. };
  5. var options = { toplevel: true };
  6. var result = UglifyJS.minify(code, options);
  7. console.log(result.code);
  8. // console.log(3+7);

nameCache 选项例子:

  1. var options = {
  2.     mangle: {
  3.         toplevel: true,
  4.     },
  5.     nameCache: {}
  6. };
  7. var result1 = UglifyJS.minify({
  8.     "file1.js": "function add(first, second) { return first + second; }"
  9. }, options);
  10. var result2 = UglifyJS.minify({
  11.     "file2.js": "console.log(add(1 + 2, 3 + 4));"
  12. }, options);
  13. console.log(result1.code);
  14. // function n(n,r){return n+r}
  15. console.log(result2.code);
  16. // console.log(n(3,7));

你可以像下面这样把名字缓存保存在文件中：

  1. var cacheFileName = "/tmp/cache.json";
  2. var options = {
  3.     mangle: {
  4.         properties: true,
  5.     },
  6.     nameCache: JSON.parse(fs.readFileSync(cacheFileName, "utf8"))
  7. };
  8. fs.writeFileSync("part1.js", UglifyJS.minify({
  9.     "file1.js": fs.readFileSync("file1.js", "utf8"),
  10.     "file2.js": fs.readFileSync("file2.js", "utf8")
  11. }, options).code, "utf8");
  12. fs.writeFileSync("part2.js", UglifyJS.minify({
  13.     "file3.js": fs.readFileSync("file3.js", "utf8"),
  14.     "file4.js": fs.readFileSync("file4.js", "utf8")
  15. }, options).code, "utf8");
  16. fs.writeFileSync(cacheFileName, JSON.stringify(options.nameCache), "utf8");

综合使用多种minify()选项的例子：

  1. var code = {
  2.     "file1.js": "function add(first, second) { return first + second; }",
  3.     "file2.js": "console.log(add(1 + 2, 3 + 4));"
  4. };
  5. var options = {
  6.     toplevel: true,
  7.     compress: {
  8.         global_defs: {
  9.             "@console.log": "alert"
  10.         },
  11.         passes: 2
  12.     },
  13.     output: {
  14.         beautify: false,
  15.         preamble: "/* uglified */"
  16.     }
  17. };
  18. var result = UglifyJS.minify(code, options);
  19. console.log(result.code);
  20. // /* uglified */
  21. // alert(10);"

生成警告提示：

  1. var code = "function f(){ var u; return 2 + 3; }";
  2. var options = { warnings: true };
  3. var result = UglifyJS.minify(code, options);
  4. console.log(result.error);    // runtime error, `undefined` in this case
  5. console.log(result.warnings); // [ 'Dropping unused variable u [0:1,18]' ]
  6. console.log(result.code);     // function f(){return 5}

生成错误提示：

  1. var result = UglifyJS.minify({"foo.js" : "if (0) else console.log(1);"});
  2. console.log(JSON.stringify(result.error));
  3. // {"message":"Unexpected token: keyword (else)","filename":"foo.js","line":1,"col":7,"pos":7}

Note: unlike uglify-js@2.x, the 3.x API does not throw errors. To
achieve a similar effect one could do the following:

  1. var result = UglifyJS.minify(code, options);
  2. if (result.error) throw result.error;

最小化选项

Minify options

  • warnings (default false) — 传 true的话，会在result.warnings中返回压缩过程的警告。传 "verbose"获得更详细的警告。

  • parse (default {}) — 如果你要指定额外的解析配置parse options,传配置对象。

  • compress (default {}) — 传false就完全跳过压缩。传一个对象来自定义 压缩配置compress options。

  • mangle (default true) — 传 false就跳过混淆名字。传对象来指定混淆配置mangle options (详情如下).

  • output (default null) — 要自定义就传个对象来指定额外的 输出配置output options. 默认是压缩到最优化。

  • sourceMap (default false) - 传一个对象来自定义
    sourcemap配置source map options.

  • toplevel (default false) - 如果你要混淆（和干掉没引用的）最高作用域中的变量和函数名，就传true。

  • nameCache (default null) - 如果你要缓存 minify()多处调用的经混淆的变量名、属性名，就传一个空对象{}或先前用过的nameCache对象。
    注意:这是个可读/可写属性。minify()会读取这个对象的nameCache状态，并在最小化过程中更新，以便保留和供用户在外部使用。

  • ie8 (default false) - 传 true 来支持 IE8.

最小化配置的结构

Minify options structure

  1. {
  2.     warnings: false,
  3.     parse: {
  4.         // parse options
  5.     },
  6.     compress: {
  7.         // compress options
  8.     },
  9.     mangle: {
  10.         // mangle options
  12.         properties: {
  13.             // mangle property options
  14.         }
  15.     },
  16.     output: {
  17.         // output options
  18.     },
  19.     sourceMap: {
  20.         // source map options
  21.     },
  22.     nameCache: null, // or specify a name cache object
  23.     toplevel: false,
  24.     ie8: false,
  25. }

sourcemap配置

Source map options

这样生成sourcemap：

  1. var result = UglifyJS.minify({"file1.js": "var a = function() {};"}, {
  2.     sourceMap: {
  3.         filename: "out.js",
  4.         url: "out.js.map"
  5.     }
  6. });
  7. console.log(result.code); // minified output
  8. console.log(result.map);  // source map

要注意，此时sourcemap并不会保存为一份文件，它只会返回在result.map中。
sourceMap.url 传入的值只用来在result.code中设置//# sourceMappingURL=out.js.map ，filename 的值只用来在sourcemap文件中设置 file属性(详情看 [规范][sm-spec])。

你可以把sourceMap.url设为true ，这样sourcemap会加在代码末尾。

你也可以指定sourcemap中的源文件根目录（sourceRoot）属性：

  1. var result = UglifyJS.minify({"file1.js": "var a = function() {};"}, {
  2.     sourceMap: {
  3.         root: "http://example.com/src",
  4.         url: "out.js.map"
  5.     }
  6. });

如果你要压缩从其他文件编译得来的带一份sourcemap的JS文件，你可以用sourceMap.content参数：

  1. var result = UglifyJS.minify({"compiled.js": "compiled code"}, {
  2.     sourceMap: {
  3.         content: "content from compiled.js.map",
  4.         url: "minified.js.map"
  5.     }
  6. });
  7. // same as before, it returns `code` and `map`

如果你要用X-SourceMap请求头，你可以忽略 sourceMap.url。

解析配置

Parse options

  • bare_returns (default false) — 支持在顶级作用域中 return 声明。
  • html5_comments (default true)
  • shebang (default true) — 支持在第一行用 #!command

压缩配置

Compress options

  • sequences(default: true) — 连续声明变量，用逗号隔开来。可以设置为正整数来指定连续声明的最大长度。如果设为true 表示默认200个，设为false或0则禁用。 sequences至少要是2,1的话等同于true（即200)。默认的sequences设置有极小几率会导致压缩很慢，所以推荐设置成20或以下。

  • properties — 用.来重写属性引用，例如foo["bar"] → foo.bar

  • dead_code — 移除没被引用的代码

  • drop_debugger — 移除 debugger;

  • unsafe (default: false) — 使用 “unsafe”转换 (下面详述)

  • unsafe_comps (default: false) — 保留< 和 <=不被换成 > 和 >=。假如某些运算对象是用get或 valueOfobject得出的时候，转换可能会不安全，可能会引起运算对象的改变。此选项只有当 comparisons和unsafe_comps 都设为true时才会启用。

  • unsafe_Func (default: false) — 当 Function(args, code)的args 和 code都是字符串时，压缩并混淆。

  • unsafe_math (default: false) — 优化数字表达式，例如2 * x * 3 变成 6 * x, 可能会导致不精确的浮点数结果。

  • unsafe_proto (default: false) — 把Array.prototype.slice.call(a) 优化成 [].slice.call(a)

  • unsafe_regexp (default: false) — 如果RegExp 的值是常量，替换成变量。

  • conditionals — 优化if等判断以及条件选择

  • comparisons — 把结果必然的运算优化成二元运算，例如!(a <= b) → a > b (只有设置了 unsafe_comps时才生效)；尽量转成否运算。例如 a = !b && !c && !d && !e → a=!(b||c||d||e)

  • evaluate — 尝试计算常量表达式

  • booleans — 优化布尔运算，例如 !!a? b : c → a ? b : c

  • typeofs — 默认 true. 转换 typeof foo == "undefined" 成 foo === void 0. 注意：如果要适配IE10或以下，由于已知的问题，推荐设成false 。

  • loops — 当do、while 、 for循环的判断条件可以确定是，对其进行优化。

  • unused — 干掉没有被引用的函数和变量。（除非设置"keep_assign"，否则变量的简单直接赋值也不算被引用。）

  • toplevel — 干掉顶层作用域中没有被引用的函数 ("funcs")和/或变量("vars") (默认是false , true 的话即函数变量都干掉)

  • top_retain — 当设了unused时，保留顶层作用域中的某些函数变量。(可以写成数组，用逗号隔开，也可以用正则或函数. 参考toplevel)

  • hoist_funs — 提升函数声明

  • hoist_vars (default: false) — 提升 var 声明 (默认是false,因为那会加大文件的size)

  • if_return — 优化 if/return 和 if/continue

  • inline — 包裹简单函数。

  • join_vars — 合并连续 var 声明

  • cascade — 弱弱地优化一下连续声明, 将 x, x 转成 x，x = something(), x 转成 x = something()

  • collapse_vars — 当 var 和 const 单独使用时尽量合并

  • reduce_vars — 优化某些变量实际上是按常量值来赋值、使用的情况。

  • warnings — 当删除没有用处的代码时，显示警告

  • negate_iife — 当立即执行函数（IIFE）的返回值没用时，取消之。避免代码生成器会插入括号。

  • pure_getters — 默认是 false. 如果你传入true，UglifyJS会假设对象属性的引用（例如foo.bar 或 foo["bar"]）没有函数副作用。

  • pure_funcs — 默认 null. 你可以传入一个名字的数组，UglifyJS会假设这些函数没有函数副作用。警告：假如名字在作用域中重新定义，不会再次检测。例如var q = Math.floor(a/b)，假如变量q没有被引用，UglifyJS会干掉它，但 Math.floor(a/b)会被保留，没有人知道它是干嘛的。你可以设置pure_funcs: [ 'Math.floor' ] ，这样该函数会被认为没有函数副作用，这样整个声明会被废弃。在目前的执行情况下，会增加开销（压缩会变慢）。

  • drop_console — 默认 false. 传true的话会干掉console.*函数。如果你要干掉特定的函数比如console.info ，又想删掉后保留其参数中的副作用，那用pure_funcs来处理吧。

  • expression — 默认 false。传true来保留终端语句中没有”return”的完成值。例如在bookmarklets。

  • keep_fargs — 默认true。阻止压缩器干掉那些没有用到的函数参数。你需要它来保护某些依赖Function.length的函数。

  • keep_fnames — 默认 false。传 true来防止压缩器干掉函数名。对那些依赖Function.prototype.name的函数很有用。延展阅读：keep_fnames 混淆选项.

  • passes — 默认 1。运行压缩的次数。在某些情况下，用一个大于1的数字参数可以进一步压缩代码大小。注意：数字越大压缩耗时越长。

  • keep_infinity — 默认 false。传true以防止压缩时把1/0转成Infinity，那可能会在chrome上有性能问题。

  • side_effects — 默认 true. 传false禁用丢弃纯函数。如果一个函数被调用前有一段/*@__PURE__*/ or /*#__PURE__*/ 注释，该函数会被标注为纯函数。例如 /*@__PURE__*/foo();

混淆配置

Mangle options

  • reserved (default [])。 传一个不需要混淆的名字的数组。 Example: ["foo", "bar"].

    • toplevel (default false)。混淆那些定义在顶层作用域的名字（默认禁用）。ß

    • keep_fnames(default false)。传true的话就不混淆函数名。对那些依赖Function.prototype.name的代码有用。延展阅读：keep_fnames 压缩配置.

    • eval (default false)。混淆那些在with或eval中出现的名字。

  1. // test.js
  2. var globalVar;
  3. function funcName(firstLongName, anotherLongName) {
  4.     var myVariable = firstLongName +  anotherLongName;
  5. }
  1. var code = fs.readFileSync("test.js", "utf8");
  3. UglifyJS.minify(code).code;
  4. // 'function funcName(a,n){}var globalVar;'
  6. UglifyJS.minify(code, { mangle: { reserved: ['firstLongName'] } }).code;
  7. // 'function funcName(firstLongName,a){}var globalVar;'
  9. UglifyJS.minify(code, { mangle: { toplevel: true } }).code;
  10. // 'function n(n,a){}var a;'

混淆属性的配置

Mangle properties options

  • reserved (default: []) — 不混淆在reserved 数组里的属性名.
  • regex (default: null) -— 传一个正则，只混淆匹配该正则的属性名。
  • keep_quoted (default: false) -— 只混淆不在括号内的属性名.
  • debug (default: false) -— 用原名字来组成混淆后的名字.
    传空字符串"" 来启用,或者非空字符串作为debu后缀。（例如"abc", foo.bar=>foo.barabc)
  • builtins (default: false) — 传 true的话，允许混淆内置的DOM属性名。不推荐使用。

输出配置

Output options

代码生成器默认会尽量输出最简短的代码。假如你要美化一下输出代码，可以传--beautify (-b)。你也可以传更多的参数来控制输出代码：

  • ascii_only (default false) — 忽略字符串和正则（导致非ascii字符失效）中的Unicode字符。
  • beautify (default true) — 是否美化输出代码。传-b的话就是设成true。假如你想生成最小化的代码同时又要用其他设置来美化代码，你可以设-b beautify=false。
  • bracketize (default false) — 永远在if, for,do, while, with后面加上大括号，即使循环体只有一句。
  • comments (default false) — 传 true 或 "all"保留全部注释,传 "some"保留部分，传正则 (例如 /^!/) 或者函数也行。
  • indent_level (default 4) 缩进格数
  • indent_start (default 0) — 每行前面加几个空格
  • inline_script (default false) — 避免字符串中出现</script中的斜杠
  • keep_quoted_props (default false) — 如果启用，会保留对象属性名的引号。
  • max_line_len (default 32000) — 最大行宽（压缩后的代码）
  • space-colon (default true) — 在冒号后面加空格
  • preamble (default null) — 如果要传的话，必须是字符串。它会被加在输出文档的前面。sourcemap会随之调整。例如可以用来插入版权信息。
  • preserve_line (default false) — 传 true 就保留空行，但只在beautify 设为false时有效。ß
  • quote_keys (default false) — 传true的话会在对象所有的键加上括号
  • quote_style (default 0) — 影响字符串的括号格式（也会影响属性名和指令）。
  • 0 — 倾向使用双引号，字符串里还有引号的话就是单引号。
  • 1 — 永远单引号
  • 2 — 永远双引号
  • 3 — 永远是本来的引号
  • semicolons (default true) — 用分号分开多个声明。如果你传false,则总会另起一行，增强输出文件的可读性。（gzip前体积更小，gzip后稍大一点点）
  • shebang (default true) — 保留开头的 shebang #! (bash 脚本)

  • width (default 80) — 仅在美化时生效，设定一个行宽让美化器尽量实现。这会影响行中文字的数量（不包括缩进）。当前本功能实现得不是非常好，但依然让美化后的代码可读性大大增强。

  • wrap_iife (default false) —传true的话，把立即执行函数括起来。 更多详情看这里
    #640