企业官网建设流程全解析

• 后端

本文是 Bluebird 的官方安装指南（对应仓库 docs/docs/install.md）的深度扩展版本。Bluebird 是一个完整实现 Promises/A+ 规范的 Promise 库，以出色的性能著称（仓库 package.json 中描述为 "Full featured Promises/A+ implementation with exceptionally good performance"）。本文覆盖浏览器<script>引入、Bower、npm、Browserify/Webpack 打包集成，以及 Node.js 环境下的安装、调试开关与平台兼容策略，读完即可在任何主流运行环境中正确安装并优化配置 Bluebird。

一、概览：三条安装路径

根据运行环境的不同，Bluebird 提供三种安装方式，对应仓库 docs/docs/install.md 中的结构：

安装后 Bluebird 通过Promise与P两个命名空间暴露自身，这一行为在后续“浏览器命名空间”一节详述。

二、浏览器安装（script 标签直引）

开发版（development）

下载未压缩的开发版文件bluebird.js，通过<script>引入：

<script src="//cdn.jsdelivr.net/npm/bluebird@3.7.2/js/browser/bluebird.js"></script>

开发版特性：开启 warnings（警告）与 long stack traces（长堆栈追踪）。这两个特性会显著拖慢性能，因此仅用于开发调试阶段，不应在生产环境使用。

生产版（production）

下载压缩后的生产版文件bluebird.min.js：

<script src="//cdn.jsdelivr.net/npm/bluebird@3.7.2/js/browser/bluebird.min.js"></script>

生产版特性：禁用 warnings 与 long stack traces，gzip 后体积约为 17.76KB（该数值来自原文档，随版本可能变化，以实际产物为准）。

注意：上方 URL 中的3.7.2对应当前仓库 package.json 的version字段。实际使用时请将版本号替换为你要安装的 Bluebird 版本。

浏览器中的命名空间与 noConflict

在无 AMD 加载器的浏览器环境中，通过<script>引入后，库会暴露在Promise和P两个命名空间下。如果页面中已存在其他 Promise 实现（或你想把全局Promise让还给原生实现），可以调用Promise.noConflict()释放Promise命名空间，并把 Bluebird 挂到自定义变量上：

var Bluebird = Promise.noConflict();

noConflict的实现位于 src/bluebird.js：它先记录加载前的全局Promise，调用时若全局Promise仍指向 Bluebird 则恢复旧值，最后返回 Bluebird 库引用供你自行命名。官方文档 docs/docs/api/promise.noconflict.md 给出典型场景——与其他 Promise 库共存：

<!-- 先加载另一个 promise 库 --> <script type="text/javascript" src="/scripts/other_promise.js"></script> <script type="text/javascript" src="/scripts/bluebird_debug.js"></script> <script type="text/javascript"> // 立刻释放 Promise 命名空间 var Bluebird = Promise.noConflict(); // 用其他 Promise 库的实例（仍占着 Promise 命名空间）转换为 Bluebird Promise： var promise = Bluebird.resolve(new Promise()); </script>

三、Bower 安装

若项目使用 Bower 管理前端依赖：

$ bower install --save bluebird

--save会把 bluebird 写入bower.json的依赖列表，方便团队与 CI 环境复现。

四、Browserify 与 Webpack 集成

通过 npm 安装后即可在打包工具中require：

$ npm install bluebird

开发 / 调试配置

Bluebird 在webpack 与 browserify 环境下默认总是判定为 development 环境（见 docs/docs/api/promise.config.md），会自动开启 long stack traces 与 warnings。因此开发构建可显式声明（也可省略）：

var Promise = require("bluebird"); // 为 webpack / browserify 配置开发/调试模式 Promise.config({ longStackTraces: true, warnings: true // 注意：node 下可加 --trace-warnings 查看 warning 的完整堆栈 });

生产 / 性能配置

生产构建必须显式关闭这两个特性，否则会因默认的 development 判定而白白承受性能开销：

var Promise = require("bluebird"); // 为 webpack / browserify 配置生产/性能模式 Promise.config({ longStackTraces: false, warnings: false });

Promise.config 完整参数

Promise.config是安装后最关键的运行时配置入口，完整签名（来自 docs/docs/api/promise.config.md）：

Promise.config(Object { warnings: boolean=false, longStackTraces: boolean=false, cancellation: boolean=false, monitoring: boolean=false, asyncHooks: boolean=false } options) -> Object;

虽然默认值都是false，但检测到 development 环境时会自动开启 long stack traces 与 warnings。全部参数示例：

Promise.config({ // 开启 warnings warnings: true, // 开启长堆栈追踪 longStackTraces: true, // 开启取消机制 cancellation: true, // 开启监控 monitoring: true, // 开启 async hooks（Node.js 9.6.0+） asyncHooks: true, });

其中warnings还支持对象形式，单独控制“遗忘 return 语句”这一警告（其对应环境变量为BLUEBIRD_W_FORGOTTEN_RETURN）：

Promise.config({ // 开启除“遗忘 return 语句”之外的全部警告 warnings: { wForgottenReturn: false } });

小结：环境判定与性能的关系

长堆栈追踪与警告的启用逻辑在 src/debuggability.js 中有源码级体现：debugging开关取决于BLUEBIRD_DEBUG环境变量或NODE_ENV === "development"，warnings与longStackTraces又分别受BLUEBIRD_WARNINGS、BLUEBIRD_LONG_STACK_TRACES的显式取值覆盖。这解释了为什么生产构建必须显式Promise.config({longStackTraces: false, warnings: false})——否则浏览器打包环境默认的 development 判定会让这两个高开销特性保持开启。

五、Node.js 安装

基本安装

$ npm install bluebird

var Promise = require("bluebird");

安装后require("bluebird")返回库入口 js/release/bluebird.js（package.json的main字段指向该构建产物，构建脚本见 package.json）。

开发环境开启调试特性

$ NODE_ENV=development node server.js

设置NODE_ENV=development会自动开启 long stack traces 与 warnings。

生产环境开启调试特性

$ BLUEBIRD_DEBUG=1 node server.js

BLUEBIRD_DEBUG会强制开启 long stack traces 与 warnings，适合在生产环境临时排查问题。

六、环境变量：全局开关的底层原理

环境变量作用于环境中运行的所有 Bluebird 实例，而非仅当前require的那个。完整说明见 docs/docs/api/environment-variables.md，且该文档明确：环境变量机制仅适用于 node.js 或 io.js。

2.x 支持的环境变量

• BLUEBIRD_DEBUG— 设为任意真值即开启 long stack traces 与 warnings
• NODE_ENV— 恰好等于development时效果等同设置BLUEBIRD_DEBUG

3.x 支持的环境变量（当前仓库为 3.7.2）

这些开关在源码 src/debuggability.js 中被逐一读取：warnings由BLUEBIRD_WARNINGS != 0 && (debugging || BLUEBIRD_WARNINGS)决定，longStackTraces同理，wForgottenReturn则是独立的环境变量。底层读取函数env(key)位于 src/util.js，仅当process.env存在时才返回对应值，因此在浏览器环境中这些变量自然失效——这正是官方文档声明“仅适用于 node.js/io.js”的原因。

组合使用示例

# 全部显式开启（等效于 BLUEBIRD_DEBUG=1） BLUEBIRD_LONG_STACK_TRACES=1 BLUEBIRD_WARNINGS=1 node app.js # 即使在 development 环境下也显式禁用 warnings NODE_ENV=development BLUEBIRD_WARNINGS=0 node app.js

注意：cancellation（取消）始终按每个 Bluebird 实例单独配置，不通过环境变量控制。

七、支持的平台与兼容策略

Bluebird 官方支持并在node.js、iojs 以及 IE7 起的浏览器上持续测试；非官方平台仅做尽力支持。仓库测试体系位于 test/mocha（含 Promise/A+ 规范测试 2.1.x–2.3.x、API 行为测试等），并通过 tools/saucelabs_runner.js 在浏览器矩阵上执行回归验证。

IE7 / IE8 的兼容别名

IE7 和 IE8不支持把关键字用作属性名，因此若必须支持这些浏览器，需要使用兼容别名调用以下 API：

这些别名在源码中是同一方法的双重挂载，例如：

• Promise.attempt = Promise["try"]，见 src/method.js
• Promise.prototype.caught = Promise.prototype["catch"]，见 src/promise.js
• Promise.prototype.lastly = Promise.prototype["finally"]，见 src/finally.js
• Promise.prototype.thenReturn与Promise.prototype["return"]同义、thenThrow与["throw"]同义，见 src/direct_resolve.js

因此，在 IE7/IE8 上应写作Promise.attempt(...)、.caught(...)、.lastly(...)、.thenReturn(...)、.thenThrow(...)以避免语法/解析问题；在其他现代环境中两套写法可互换。

长堆栈追踪的浏览器支持范围

Long stack traces 仅受以下浏览器支持：Chrome、较新的 Firefox 以及 Internet Explorer 10+。在旧 IE 或不支持的浏览器中，该特性不会生效，相关配置会被忽略。

八、安装后的最佳实践清单

综合以上内容，给出实操建议：

1. 浏览器直接引入：开发用未压缩的bluebird.js（带警告与长堆栈），生产用bluebird.min.js（gzip 约 17.76KB，无调试开销）。
2. 与既有 Promise 库共存：加载后立刻var Bluebird = Promise.noConflict()释放全局Promise命名空间，参考 docs/docs/api/promise.noconflict.md。
3. Webpack / Browserify：开发构建可依赖自动的 development 判定；生产构建务必显式Promise.config({ longStackTraces: false, warnings: false })。
4. Node.js：开发用NODE_ENV=development；生产临时排查用BLUEBIRD_DEBUG=1；需要细粒度控制时组合使用BLUEBIRD_WARNINGS、BLUEBIRD_LONG_STACK_TRACES、BLUEBIRD_W_FORGOTTEN_RETURN。
5. 兼容旧浏览器：面向 IE7/IE8 时统一改用attempt、caught、lastly、thenReturn、thenThrow别名。
6. 按实例配置：cancellation、asyncHooks 等特性按实例通过Promise.config设置，不受环境变量影响。

以上安装路径、配置项与平台约束均以当前仓库文档（docs/docs/install.md、docs/docs/api/promise.config.md、docs/docs/api/environment-variables.md）与源码实现为准，版本号为仓库 package.json 中声明的 3.7.2。

• 后端