企业官网建设流程全解析

• 接口测试
• CLI

Newman 是 Postman 官方的命令行集合运行器（collection runner），允许开发者直接从终端运行和测试 Postman Collection，并轻松集成到 CI/CD 构建系统中。本文基于仓库根目录的 MIGRATION.md 编写，完整梳理 Newman 从 V2 一路升级到 V6 过程中涉及的 Node.js 版本要求、CLI/库接口变更、配置项重命名、默认行为调整等全部破坏性变更，并结合当前仓库（v6.2.3）的源码实现逐一佐证，帮助你在升级时一次性完成脚本、参数和数据的改造，避免踩坑。

一、更新到最新版本：升级前必读

MIGRATION.md 开篇就强调：如果你正从旧版本升级 Newman，务必通读全文，理解各版本之间的行为差异，再动手升级。官方给出的标准升级流程如下：

1. 升级 Newman

$ npm update -g newman

2. 校验安装结果

$ newman --version # Should show the latest version of Newman $ npm show newman version # Should show the same version as of above

两条命令输出的版本号应当一致，确认全局安装的 Newman 已更新到位。

从当前仓库 package.json 可以看到，Newman 通过engines字段声明"node": ">=16"，并在 lib/node-version-check/index.js 中利用semver在 CLI 启动时检测运行环境：

if (!semver.satisfies(currentNodeVersion, requiredNodeVersion)) { console.error([colors.red('newman:'), 'required node version', requiredNodeVersion].join(' ')); process.exit(1); }

即：当当前 Node.js 版本不满足要求时，Newman 会直接报错并退出。因此升级 Newman 前务必先检查 Node.js 版本，这正是下文各版本迁移均以"升级 Node.js"开头的根本原因。

二、从 V5 迁移到 V6

1. 升级 Node.js

Newman v6.0 要求Node.js >= v16，运行时依赖也全部升级到了各自的最新版本。这一约束同样体现在 package.json 的engines字段中。

2. 最新版 Postman Runtime

Newman v6 采用最新版本的 Postman Runtime 依赖，带来了多项改进与缺陷修复，值得关注的新增能力包括：

• JWT 认证（JWT authentication）
• NTLMv2 认证（NTLMv2 authentication）
• 脚本中的 Promise 执行（Promise execution in scripts）
• raw 模式请求体中的 JSON 注释剥离（Stripping JSON comments in the raw mode body）

其中"脚本中的 Promise 执行"意味着在 Pre-request Script 和 Test Script 中可以直接书写Promise/async/await风格的异步逻辑，而无需依赖旧的异步回调模式，这是从 Postman 应用到 CLI 保持体验一致的关键改进之一。

3. Docker 镜像变更

Newman v6彻底移除了对废弃镜像postman/newman_alpine33与postman/newman_ubuntu1404的支持。目前仅保留两个官方镜像，且均升级至 Node.js v16：

• postman/newman:alpine（轻量级）
• postman/newman:ubuntu

关于镜像的详细用法，可参考仓库 docker/README.md。例如挂载本地集合目录到镜像内运行：

docker run -v ~/collections:/etc/newman -t postman/newman:ubuntu \ run "HTTPBinNewmanTest.json.postman_collection" \ --environment="HTTPBinNewmanTestEnv.json.postman_environment" \ --reporters="json,cli" --reporter-json-export="newman-results.json"

注意：两个镜像的--entrypoint不同，Alpine 镜像应使用/bin/sh，Ubuntu 镜像使用/bin/bash。

三、从 V4 迁移到 V5

Newman v5.0 移除了对Node v6 与 v8的支持，同时升级了内置的 URL 处理器与 CSV 解析器。

1. 升级 Node.js

Newman v5 要求Node.js >= v10。

2. 下一代 URL 处理器（Next-Generation URL Processor）

Newman v5 引入了改进后的 URL 处理系统，修复了旧处理器在 URL解析与编码方面的多个限制。这意味着：

• 包含特殊字符、非 ASCII 字符、复杂 query 参数的 URL，在 V5 中的解析结果可能与 V4 不同；
• 如果你的集合依赖旧版 URL 编码行为（例如手动编码后再次被编码），升级后需回归验证。

仓库侧的体现是：Newman 的请求器强制启用useWhatWGUrlParser: true（见 lib/run/index.js 中requester配置），即采用 WHATWG URL 标准解析 URL。

3. CSV 解析器重构

长期以来 Newman 与 Postman App 的 CSV 解析行为存在差异，v5 修复了这一不一致。具体变更如下。

转义字符改为双引号

默认转义字符从\（反斜杠）改为"（双引号）。

V4 CSV 输入

id, name "\"1\"", "foo \"bar\" baz"

V5 等价写法

id, name """1""", "foo ""bar"" baz"

可以看到，V5 中字段内如需包含双引号，需要将单个双引号翻倍（""），这与 Postman App 及多数 CSV 实现（如 RFC 4180）保持一致。

放宽解析规则（Relaxed parsing）

1. 保留未加引号字段内部的引号（Preserve quotes inside unquoted field）
2. 丢弃列数不一致的行（Discard inconsistent columns count）
3. 检测并剔除字节顺序标记 BOM（Detect and exclude the byte order mark）

这些规则在仓库源码中有精确对应。在 lib/run/options.js 的iterationData加载器中，CSV 解析参数如下：

parseCsv(data, { columns: true, // 首行作为列名 escape: '"', // 转义字符为双引号 cast: csvAutoParse, // 字段类型自动转换 trim: true, // 忽略分隔符周围的空白 relax: true, // 允许在未加引号的字符串中使用引号 relax_column_count: true, // 忽略列数不一致的行 bom: true // 从输入中剥离字节顺序标记（BOM） }, cb);

每个选项都能在文档中找到对应描述。仓库还提供了针对性的集成测试目录，例如 test/integration/comma-test-csv/（验证带逗号字段的解析）与 test/integration/csv-with-bom/（验证 BOM 剥离），可作为升级后验证 CSV 行为的参考样例。

四、从 V3 迁移到 V4

Newman v4.0 移除了对Node v4的支持，同时废弃了全部 V2 时代的 CLI 选项，并将内置的 HTML 报告器独立为单独的报告器包。

1. 升级 Node.js

Newman v4 要求Node.js >= v6。

2. 废弃的 CLI 选项

Newman v4 移除了所有已废弃的 V2 CLI 选项（具体清单见文末"V2 到 V3 迁移指南"章节）。其中值得一提是--no-color：该选项因color选项的语义调整而被移除。

3. 使用color选项（CLI 与 Library 行为均变更）

与 Newman v3.x 不同，v4 中color选项单独即可启用或禁用彩色 CLI 输出。

CLI

1. 启用彩色输出

# V3 命令 $ newman run collection.json --color # V4 等价命令 $ newman run collection.json --color on

2. 禁用彩色输出

# V3 命令 $ newman run collection.json --no-color # V4 等价命令 $ newman run collection.json --color off

Library

1. 启用彩色输出

// V3 写法 newman.run({ collection: 'collection.json', reporters: ['cli'], color: true }, callback); // V4 等价写法 newman.run({ collection: 'collection.json', reporters: ['cli'], color: 'on' }, callback);

2. 禁用彩色输出

// V3 写法 newman.run({ collection: 'collection.json', reporters: ['cli'], noColor: true }, callback); // V4 等价写法 newman.run({ collection: 'collection.json', reporters: ['cli'], color: 'off' }, callback);

注意：默认行为是自动检测终端是否支持颜色，再决定是否启用。这一默认行为可通过将color显式设为on或off来覆盖。

这一设计在当前仓库中有完整的源码链支撑：

• CLI 侧，bin/newman.js 将--color定义为'--color <value>'，接受auto|on|off三个取值，默认auto；
• bin/util.js 中的colorOptions会对非法取值直接抛错：invalid value \${value}` for --color. Expected: auto|on|off`；
• 报告器侧，lib/reporters/cli/cli-utils.js 的noTTY(color)函数实现了完整判定逻辑：

noTTY: function (color) { return (color === 'off') || (color !== 'on') && (!process.stdout.isTTY); }

即：on强制启用颜色；off强制禁用；auto（其余情况）则根据process.stdout.isTTY是否成立来判断终端是否支持颜色。同时 lib/reporters/cli/index.js 在初始化时执行cliUtils.noTTY(options.color) && colors.disable()完成颜色禁用。

4. HTML 报告器独立为单独包

内置的 HTML 报告器已迁移为独立报告器，需要单独安装：

$ npm install -g newman-reporter-html

如果 Newman 是本地安装的，应去掉-g标志进行本地安装。注意，仓库 lib/run/index.js 的knownReporterErrorMessages中依然保留了 HTML 报告器的安装提示，当引用html报告器但未安装时，Newman 会输出run \npm install newman-reporter-html`` 的引导信息。

5. 弃用 v1 集合格式

Newman >= v4 弃用对 v1 Collection 格式的支持，建议使用 Postman 原生应用将集合导出为 v2 格式。仓库源码 lib/run/options.js 的processCollection函数清晰展示了这一降级策略：

if (util.isV1Collection(collection)) { console.warn('newman: Newman v4 deprecates support for the v1 collection format'); console.warn(' Use the Postman Native app to export collections in the v2 format\n'); return transformer.convert(collection, COLLECTION_TRANSFORMER_OPTION, callback); }

当检测到 v1 集合时，Newman 会打印弃用警告，并通过postman-collection-transformer（转换参数为inputVersion: '1.0.0', outputVersion: '2.1.0'）自动将其转换为 v2 后继续运行。这也意味着你可以在升级期间继续使用旧集合，但应当尽快在 Postman App 中重新导出。

6. CSV 自动解析修复

一个针对 CSV 的修复被合入：避免解析引号内的数字。例如"000123"将不再像以前那样被解析成123。对应源码是 lib/run/options.js 中的csvAutoParse：

csvAutoParse = function (value, context) { if (context.quoting) { // avoid parsing quoted values return value; } if (util.isInt(value)) { return parseInt(value, 10); } if (util.isFloat(value)) { return parseFloat(value); } return value; };

核心逻辑：context.quoting为真（字段被引号包裹）时原样返回字符串，不做任何类型转换；只有未加引号的字段才会按整数/浮点数自动转换。这一修复解决了多位数字开头的 ID、订单号等在迭代数据中被意外截断的经典问题。

7. 默认超时改为无限

从 V4 起，所有超时选项的默认值均为 Infinity（无限）。这在使用时意味着：如果你依赖默认超时来兜底，升级后必须显式设置--timeout、--timeout-request或--timeout-script。当前仓库 lib/run/index.js 中传给 Runtime 的超时配置也印证了"0 表示不超时"的约定：

timeout: { global: options.timeout || 0, request: options.timeoutRequest || 0, script: options.timeoutScript || 0 },

五、从 V2 迁移到 V3（V2 to V3 Migration Guide）

Newman v3.0 是一次从零开始的重写：它与其它 Node 库的配合更好，并为并行集合运行、单次运行内并行请求等未来特性预留了灵活性。最重要的是，Newman 开始使用Postman Runtime，从而在 Postman App 与 CLI 之间提供一致的运行体验。

1. 功能总览

1. 集合运行统一通过run命令发起，见下方各示例。
2. 终端输出更丰富、信息量更大，彩色高亮标出错误发生的位置。
3. 支持从URL加载环境（environment）、全局变量（globals）、集合（collection）以及迭代数据（iteration data）。
4. 作为Node 库使用时更加友好，v3.0 从设计之初就秉持"库优先"（library-first）的思路。
5. 内部代码组织更合理，便于更快地实现新特性。

2. 自 v2.x 以来的变化

对大多数简单用例而言，迁移到 v3.x 非常轻松——Newman 刻意保留了旧 CLI 选项的兼容（升级后"应该就能跑"）。但官方明确指出：旧选项很快会被停用，新特性只能通过新选项使用。

由于 v3.x 是完整重写，需要注意行为细节的差异：报告输出略有不同、CLI 输出完全重构、集合运行会继承新 Postman Runtime 的全部特性（如 jQuery 弃用、DOM 中止支持）等。

3. HTML、XML 等输出统一为 "reporters"

Newman v3 采用reporters（报告器）模型：原先属于 Newman 核心的功能被移入报告器，相应 CLI 选项改为通过--reporter-*访问。即便部分报告器功能被精简，报告器输出却更加详细——这是为了把非核心代码从 Newman 核心剥离，为以后接入外部报告器插件做准备。

当前仓库 lib/run/index.js 中的内置报告器清单印证了这套模型：

defaultReporters = { cli: require('../reporters/cli'), json: require('../reporters/json'), junit: require('../reporters/junit'), progress: require('../reporters/progress'), emojitrain: require('../reporters/emojitrain') },

外部报告器（如newman-reporter-html）则通过newman-reporter-<name>的命名约定动态加载。

4.--no-color自动化

Newman 现在自动检测终端是否支持颜色，因此该标志不再需要显式提供；但--no-color仍可用于强制关闭终端输出颜色（这正是后来 V4 演化为--color auto|on|off三态选项的前身）。

5. 废弃的 CLI 选项

-S --noTestSymbols

该开关不再生效——Newman v3 已在 Windows 平台上妥善处理 Unicode 输出。

-p, --pretty

该开关原本用于让导出的 JSON 文件以美化格式输出。Newman v3总是以美化格式导出，因此该开关已无必要。如需压缩格式，请对导出文件自行做 JSON 压缩处理。

6. 完整 CLI 迁移对照表

下表枚举了 V2 中被废弃（deprecated）/停用（discontinued）或重命名（renamed）的选项。V3 等价列中的选项用于run命令；V2 旧选项在 V2 模式下依然可用（无需run），但会在下一个大版本中被移除。

状态说明：Deprecated表示选项仅为向后兼容保留，将在下一大版本移除；Discontinued表示不再支持，或已由默认行为实现。未列入表格的选项与 V2 保持一致。

示例 1：配置全部基础选项（不含报告器）的集合运行

# V2 命令 newman --collection collection.json --environment env.json --data data.csv --globals globals.json --number 2 --exportGlobals globalOut.json --exportEnvironment envOut.json --delay 10 --requestTimeout 5000 --noTestSymbols --tls --exitCode --whiteScreen --avoidRedirects --stopOnError # V3 等价命令 newman run collection.json --environment env.json --iteration-data data.csv --globals globals.json --iteration-count 2 --export-globals globalOut.json --export-environment envOut.json --delay-request 10 --timeout-request 5000 --disable-unicode --suppress-exit-code --ignore-redirects --bail

示例 2：配置各种报告器任务的集合运行

# V2 命令 newman --url https://a.com/collection.json --environment-url https://a.com/env.json --noColor --outputFile jsonOut.json --testReportFile xmlOut.xml --html htmlOutput.html --outputFileVerbose verboseOut.log # V3 等价命令 newman run https://a.com/collection.json --environment https://a.com/env.json --reporters cli,html,json,junit --reporter-json-export jsonOut.json --reporter-junit-export xmlOut.xml --reporter-html-export htmlOutput.html

注意 V3 中集合与环境都可以直接以 URL 形式传给run命令。

CLI 迁移表

几个需要特别留意的语义变化：

• -x从 V2 的--exitCode（失败时返回非零退出码）反转为 V3 的--suppress-exit-code（强制退出码为 0，即忽略失败结果）；
• -s --stopOnError演变为--bail，且 V3 的--bail在 lib/run/index.js 中还支持folder、failure修饰符；
• --disable-unicode取代了--noTestSymbols，对应仓库 bin/newman.js 中的--disable-unicode选项（强制将 Unicode 符号替换为纯文本等价物）。

7. Library 使用方式迁移

示例 1：配置全部基础选项（不含报告器）的集合运行

// V2 写法（newman.execute） newman.execute({ collection: 'collection.json', environment: 'env.json', data: 'data.csv', globals: 'globals.json', number: 2, exportGlobals: 'globalOut.json', exportEnvironment: 'envOut.json', delay: 10, stopOnError: true, requestTimeout: 5000, noTestSymbols: true, tls: true, exitCode: true, whiteScreen: true, avoidRedirects: true }, callback); // V3 等价写法（newman.run） newman.run({ collection: 'collection.json', environment: 'env.json', iterationData: 'data.csv', globals: 'globals.json', iterationCount: 2, exportGlobals: 'globalOut.json', exportEnvironment: 'envOut.json', delayRequest: 10, bail: true, timeoutRequest: 5000, disableUnicode: true, suppressExitCode: true, ignoreRedirects: true }, callback);

示例 2：配置各种报告器任务的集合运行

// V2 写法 newman.execute({ collection: 'https://a.com/collection.json', environment: { "id": "my-id", "name": "testEnv", "values": [ { "key": "env", "value": "env2" }, { "key": "data", "value": "env2" } ] }, globals: [ { key: "var1", value: "/get", enabled: true }, { key: "var2", value: "Global Bar" } ], outputFile: 'jsonOut.json', testReportFile: 'xmlOut.xml', html: 'htmlOutput.html', outputFileVerbose: 'verboseOut.log' }, callback); // V3 等价写法 newman.run({ collection: 'https://a.com/collection.json', environment: { "id": "my-id", "name": "testEnv", "values": [ { "key": "env", "value": "env2" }, { "key": "data", "value": "env2" } ] }, iterationData: [ {a: 1}, {a: 2} ], globals: [ { key: "var1", value: "/get", enabled: true }, { key: "var2", value: "Global Bar" } ], reporters: ['html', 'junit', 'json'], reporter: { html: { export: 'htmlOutput.html' }, junit: { export: 'xmlOut.xml' }, json: { export: 'jsonOut.json' } } }, callback);

V3 的库接口变化要点：入口从newman.execute改为newman.run；环境、全局变量、迭代数据等均可直接传入JSON 对象/数组（不再局限于文件路径）；所有报告相关输出统一收敛到reporters+reporter两级配置。

Library 迁移表

六、小结：升级路径与核对清单

结合 MIGRATION.md 与当前仓库源码，将各版本升级要点汇总如下，可作为你的逐级核对清单：

升级时建议按以下顺序自查：

1. Node.js 版本：确认满足 v16+（当前 package.json 的engines要求），否则 CLI 会在启动阶段被 lib/node-version-check/index.js 拦截；
2. 脚本参数：逐个对照"CLI 迁移表"与"Library 迁移表"，将 V2 旧选项替换为 V3+ 新选项，尤其是--suppress-exit-code的退出码语义反转；
3. CSV 迭代数据：检查含引号的字段写法是否符合""转义规则，确认"000123"这类引号内数字不再被自动转成数值；
4. 超时配置：确认 CI 脚本中显式设置了--timeout-request等超时参数，避免依赖已改为无限值的默认行为；
5. Docker 镜像：将镜像名从废弃的newman_alpine33/newman_ubuntu1404迁移到postman/newman:alpine或postman/newman:ubuntu；
6. 报告器：如使用 HTML 报告，确认已安装newman-reporter-html，或直接使用内置的cli、json、junit、progress、emojitrain报告器（见 lib/run/index.js）。

如需完整的当前版本支持选项清单，请查阅仓库 README.md 中的 Command Line Options 与 API Reference 章节。

• 接口测试
• CLI