Sails 环境特定配置指南：深入解析 config/env/ 目录-平芜编程栈

后端

【免费下载链接】sails

Realtime MVC Framework for Node.js

项目地址：https://gitcode.com/gh_mirrors/sa/sails

导读

config/env/是 Sails 应用中存放"环境特定配置"的专用目录，用于按运行环境（development、production、staging 等）隔离 API 密钥、远程数据库密码等敏感或差异化设置。读完本文，你将掌握config/env/目录的两种组织方式（子目录与单文件）、它们的加载与覆盖规则，理解 Sails 底层配置合并机制（moduleloader 钩子）的实现细节，并能在实际项目中正确规划生产环境配置方案。

config/env/ 目录的定位

在 Sails 应用解剖（Anatomy）体系中，config/ 目录存放所有允许自定义与配置 Sails 应用的配置文件。其中 config/env/ 是专门面向"运行环境"的一层：

This folder contains various environment-specific settings such as API keys or remote database passwords. Depending on the environment Sails is lifted in, the appropriate configuration file in this folder will load.

即：该目录存放 API 密钥、远程数据库密码等环境相关设置；Sails 在启动（lift）时，会根据当前运行环境加载config/env/中对应的配置文件。环境特定配置的完整概念说明见 Concepts > Configuration > Environment-specific files。

两种环境特定配置形式与加载规则

Sails 支持两种环境特定配置形式，它们的加载时机与优先级各不相同：

环境子目录：config/env/<environment-name>/下的所有文件，仅当 Sails 以<environment-name>环境启动时才会被加载。例如config/env/production/下的文件仅在 production 模式下生效。
环境单文件：config/env/<environment-name>.js，同样仅在该环境启动时加载，并且会合并覆盖环境子目录中的设置。例如config/env/production.js的配置优先级高于config/env/production/目录中的文件。

典型的目录结构如下：

config/ ├── env/ │ ├── development.js # 开发环境配置（可选） │ ├── production.js # 生产环境配置（仓库默认生成的模板文件） │ └── production/ # 生产环境子目录（可选，优先级低于 production.js） ├── local.js # 本地环境覆盖（优先级最高，不入版本库） ├── models.js ├── routes.js └── ...

仓库默认的 production.js 模板

Sails 新项目默认在config/env/下生成 production.js 模板文件，其定位为：

This file will be loaded when Sails is running inproductionmode. If using the CLI commandsails lift --prod, these settings will be loaded.

即该文件在 Sails 以 production 模式运行时被加载，既可以通过NODE_ENV=production环境变量触发，也可以通过sails lift --prod命令行参数触发。

如何切换运行环境

默认情况下，Sails 应用运行在development环境。推荐的环境切换方式是通过NODE_ENV环境变量：

NODE_ENV=production node app.js

除了NODE_ENV，从源码实现看（lib/app/configuration/load.js），Sails 还提供了几个命令行快捷方式，它们会在配置加载阶段被映射为对应的sails.config.environment值：

命令行参数	映射环境	备注
`--prod`	`production`	官方更推荐使用`NODE_ENV=production`
`--staging`	`staging`	便于模拟预发布环境
`--dev`	`development`	已废弃，使用时会打印弃用警告

此外，--safe、--alter、--drop会映射为models.migrate的对应取值（safe/alter/drop），--verbose/--silly/--silent会映射为日志级别，--redis则会把 session 与 sockets 的 adapter 切到对应的 Redis 实现。这些快捷方式共同构成了环境相关的"一键配置"体验。

源码剖析：config/env/ 的加载机制

config/env/的加载并非魔法，其核心实现在 moduleloader 钩子的loadUserConfig()方法中。该方法通过async.auto并行收集四类配置来源：

config/*：config/目录下的普通配置文件（排除locales、local.*以及env子目录）；
config/local：config/local.js本地覆盖文件；
config/env/**：config/env/<env>/环境子目录中的文件；
config/env/*：config/env/<env>.js环境单文件。

其中环境名的确定逻辑值得注意：

var env = sails.config.environment || asyncData['config/local'].environment || 'development';

即环境名按以下优先级确定：命令行/环境变量显式指定的sails.config.environment→config/local.js中声明的environment→ 默认development。换言之，如果命令行已经通过--prod或NODE_ENV指定了环境，该值优先；否则会退而查看config/local.js里是否声明了环境；最后才默认 development。

环境子目录与单文件的加载都使用了includeAll.aggregate并带有optional: true，这意味着目录不存在或文件缺失不会报错——这正是为什么新建项目即使没有config/env/development/目录也能正常启动。

最终合并顺序见该方法结尾：

var config = mergeDictionaries( asyncData['config/*'], asyncData['config/env/**'], asyncData['config/env/*'], asyncData['config/local'] );

结合注释可知合并优先级（从低到高）：普通配置 < 环境子目录 < 环境单文件 <local.js。也就是说，config/env/<env>.js覆盖config/env/<env>/子目录，而config/local.js覆盖一切环境特定配置。

配置优先级全景

理解config/env/的价值，需要把它放进 Sails 完整的配置优先级体系中。依据 Concepts > Configuration 与 load.js 顶部注释，通过sails lift或node app.js启动时，配置来源按优先级从高到低为：

命令行参数（由 minimist 解析），如sails lift --custom.mailgun.apiToken='foo'；
以sails_为前缀、双下划线__分隔嵌套层级的环境变量，如sails_port=1492 sails lift；
应用目录下（或向上逐级查找）的.sailsrc文件；
用户主目录中的全局.sailsrc文件；
config/local.js；
config/env/*中与当前NODE_ENV匹配的文件（默认 development）；
config/目录下的其他普通配置文件。

而以编程方式调用sails.lift()/sails.load()时，最高优先级变为传入的配置覆盖字典（overrides），其余次序相同。这正是config/env/在整条链路上的定位：它高于普通 config 文件，但低于 local.js、.sailsrc、环境变量与命令行参数。

值得强调的是NODE_ENV与PORT两个特殊环境变量：NODE_ENV=production会设置sails.config.environment，PORT则是设置sails.config.port的便捷方式（为向后兼容保留）。二者对命令行启动与编程式启动都生效，除非被显式覆盖。常见组合用法：

PORT=443 NODE_ENV=production sails lift

local.js：本地优先，绝不入库

config/local.js 用于存放仅适用于你本地开发环境（如个人笔记本电脑）的设置，例如只属于自己的数据库密码或邮箱凭据。它覆盖config/中所有其他文件（包括env/子目录），是环境特定配置之上的"最后一层本地覆盖"。默认情况下config/local.js已被列入.gitignore，不会提交到版本库，因此你可以放心地把个人信息写进去而不必担心泄露。在线上生产环境，官方建议完全忽略该文件，改用env/production.js、环境变量或两者组合来配置生产覆盖。

生产环境最佳实践

结合前文机制，规划生产环境配置时推荐遵循以下策略：

敏感凭据优先走环境变量：如sails_datastores__default__password='...' sails lift，这样数据库密码、API token 不会进入代码仓库；也可以利用 PaaS 平台提供的 UI 管理这些变量。
非敏感的生产差异配置放入config/env/production.js：例如关闭蓝图快捷路由、开启 CSRF、配置日志级别等生产相关设置。
需要区分多套非默认环境时使用环境子目录：例如config/env/staging/配合sails lift --staging使用，子目录与单文件（staging.js）可并存，后者优先级更高。
本地调试差异放入config/local.js：并确保它永远不被提交。

一个综合示例：假设你要在 443 端口以 production 模式启动，同时通过命令行覆盖 CORS 允许来源：

PORT=443 NODE_ENV=production sails_security__cors__allowOrigins='["https://example.com"]' sails lift

运行时你可以随时通过sails.config（默认暴露在全局）读取合并后的最终配置，例如在代码中做生产环境校验：

if (sails.config.environment === 'production' && !sails.config.security.csrf) { throw new Error('STOP IMMEDIATELY ! CSRF should always be enabled in a production deployment!'); }

需要注意：部分配置项（如port）只在 lift 启动过程中被读取，运行期直接修改sails.config.port不会生效，必须通过配置文件或命令行参数修改后重启服务。

小结

config/env/是 Sails "约定优于配置"哲学的典型体现：你只需按环境名组织文件（子目录或单文件），Sails 的 moduleloader 就会在启动时按既定规则自动加载与合并。理解其加载顺序、环境名解析逻辑以及与local.js、环境变量、命令行参数的优先级关系，是构建安全、可维护的多环境 Sails 应用的基础。进一步的配置参考可继续阅读 Concepts > Configuration、sails.config 参考以及 .sailsrc 文件说明。