【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载本篇围绕 AWS SDK for JavaScript v3 的aws-sdk/credential-providers包展开讲清 Node.js 客户端的默认凭证解析行为以及共享配置文件fromIni()、环境变量fromEnv()、运行时 Assume RolefromTemporaryCredentials()、Kubernetes IRSA 的 OIDC 令牌文件fromTokenFile()、IAM Identity CenterfromSSO()和 Cognito 身份池等显式凭证来源的正确用法与陷阱。读完后你可以为任意 AWS SDK v3 客户端选对凭证来源并在本地、容器、K8s、浏览器等多运行环境下写出可复制可运行的凭证代码。该内容源自 Context Hub 仓库中 credential-providers 文档元数据显示 SDK 版本 3.1007.0维护者提供2026-03-13 更新。何时需要这个包AWS SDK v3 客户端默认回答“怎么签请求”而aws-sdk/credential-providers回答的是“凭证从哪来”。当你需要显式指定以下任一来源时就安装并使用它共享配置文件~/.aws/credentials、~/.aws/config与AWS_PROFILE选择IAM Identity CenterAWS SSOSTS 假设角色assume-roleOIDC / Web Identity如 Kubernetes service account 令牌文件Cognito 身份池浏览器 / 移动端ECS / EC2 元数据端点在客户端构造器之外单独获取凭证如 S3 预签名 URL 工具函数。安装时provider 包要和你实际调用的 AWS 服务客户端一起装npm install aws-sdk/credential-providers aws-sdk/client-s3示例还会用到 STS 客户端与预签名器npm install aws-sdk/client-sts aws-sdk/s3-request-presigner其中aws-sdk/client-sts的用法可对照仓库中 STS 客户端文档aws-sdk/s3-request-presigner的完整签名流程见 s3-request-presigner 文档。黄金规则默认链与显式提供的边界维护者文档给出了四条清晰的使用准则在 Node.js 中AWS SDK v3 客户端已经使用默认凭证提供者链——大多数情况下你根本不需要传credentials只有需要显式凭证来源、非默认 profile、assume-role、SSO、令牌文件认证、Cognito 身份池或需要在客户端构造器之外拿凭证时才用这个包fromIni()、fromEnv()、fromProcess()、fromTokenFile()、fromSSO()、fromNodeProviderChain()、fromContainerMetadata()、fromInstanceMetadata()是Node.js 专用fromCognitoIdentity()、fromCognitoIdentityPool()、fromWebToken()、fromTemporaryCredentials()在浏览器和原生应用中也可用。默认 Node.js 行为什么都不传就对了这个包正是 Node.js AWS SDK 客户端默认凭证行为的底层实现。只要环境里已有可用凭证下面这段就足够import { S3Client, ListBucketsCommand } from aws-sdk/client-s3; const s3 new S3Client({ region: process.env.AWS_REGION ?? us-east-1, }); const result await s3.send(new ListBucketsCommand({})); console.log(result.Buckets);本地开发环境的典型配置export AWS_REGIONus-east-1 # 方案 1共享配置文件 export AWS_PROFILEdev # 方案 2静态或临时环境变量凭证 export AWS_ACCESS_KEY_ID... export AWS_SECRET_ACCESS_KEY... export AWS_SESSION_TOKEN...如果你想显式使用与默认完全相同的链典型场景是构造器外取凭证用fromNodeProviderChain()import { fromNodeProviderChain } from aws-sdk/credential-providers; const credentials fromNodeProviderChain(); // 传给任意客户端或在工具函数里 await credentials()共享配置文件fromIni()与 profile 语义当凭证来自~/.aws/credentials、~/.aws/config、assume-role profile或AWS_PROFILE选中的 profile 时使用fromIni()import { S3Client, ListBucketsCommand } from aws-sdk/client-s3; import { fromIni } from aws-sdk/credential-providers; const profile process.env.AWS_PROFILE ?? app-dev; const s3 new S3Client({ region: process.env.AWS_REGION ?? us-west-2, profile, credentials: fromIni({ profile }), }); const result await s3.send(new ListBucketsCommand({})); console.log(result.Buckets);配套的共享文件示例。~/.aws/credentials中存放基础凭证[source-user] aws_access_key_id AKIAEXAMPLE aws_secret_access_key SECRETEXAMPLE~/.aws/config中定义一个通过source_profile假设角色的 profile[profile app-dev] region us-west-2 role_arn arn:aws:iam::123456789012:role/AppDeveloper source_profile source-user除了source_profilefromIni()还支持用credential_source在不指定source_profile的情况下完成角色假设[profile app-prod] region us-west-2 role_arn arn:aws:iam::123456789012:role/AppProduction credential_source Ec2InstanceMetadata维护者文档列出的受支持credential_source取值Ec2InstanceMetadataEnvironmentEcsContainerfromIni()的常用选项选项说明profile要读取的 profile 名filepath覆盖默认的~/.aws/credentials路径configFilepath覆盖默认的~/.aws/config路径mfaCodeProviderprofile 需要 MFA 时必填提供验证码的回调clientConfig覆盖内部用于解析凭证的 STS / SSO 客户端配置版本相关说明自 AWS SDK v3.714.0 起AWS 客户端还接受顶层profile字段。在当前文档对应的包版本中直接在客户端上设置profile往往是最简单的 profile 选择方式。环境快速失败fromEnv()fromEnv()只从环境变量取凭证缺失时给出明确报错适合要求“要么有环境凭证、要么立刻失败”的服务import { STSClient, GetCallerIdentityCommand } from aws-sdk/client-sts; import { fromEnv } from aws-sdk/credential-providers; const sts new STSClient({ region: process.env.AWS_REGION ?? us-east-1, credentials: fromEnv(), }); const caller await sts.send(new GetCallerIdentityCommand({})); console.log(caller.Arn);fromEnv()读取的变量AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYAWS_SESSION_TOKENAWS_CREDENTIAL_EXPIRATION用GetCallerIdentity验证当前身份是排查凭证问题的标准动作——它不要求猜测凭证究竟来自环境变量、profile、ECS 还是 EC2直接返回当前 principal 的Account/Arn/UserId这一点在 STS 文档中也被列为最快捷的“身份 sanity check”。运行时假设角色fromTemporaryCredentials()当需要在代码里而不是靠预配置 profile 来 assume role 时使用import { STSClient, GetCallerIdentityCommand } from aws-sdk/client-sts; import { fromIni, fromTemporaryCredentials } from aws-sdk/credential-providers; const credentials fromTemporaryCredentials({ masterCredentials: fromIni({ profile: source-user }), clientConfig: { region: us-east-1, }, params: { RoleArn: arn:aws:iam::123456789012:role/DeployRole, RoleSessionName: deploy-session, DurationSeconds: 3600, }, }); const sts new STSClient({ region: us-east-1, credentials, }); const caller await sts.send(new GetCallerIdentityCommand({})); console.log(caller.Arn);要点masterCredentials本身可以是任意 provider示例中来自fromIniparams就是传给 STSAssumeRole的参数。如果请求包含SerialNumberMFA还必须同时提供mfaCodeProviderSDK 才能拿到 MFA 验证码。该 provider 在浏览器和原生应用中也可用是客户端侧“基础凭证 → 收窄权限角色”这一联邦模式的通用入口。OIDC / IRSAfromTokenFile()当 OIDC 令牌在磁盘上、AWS 端需要调用AssumeRoleWithWebIdentity时使用——这正是 KubernetesEKS / IRSAservice account 令牌文件的典型模式。所需输入来自函数选项或环境变量export AWS_REGIONus-west-2 export AWS_WEB_IDENTITY_TOKEN_FILE/var/run/secrets/eks.amazonaws.com/serviceaccount/token export AWS_ROLE_ARNarn:aws:iam::123456789012:role/EksAppRole export AWS_ROLE_SESSION_NAMEmy-appimport { S3Client, ListBucketsCommand } from aws-sdk/client-s3; import { fromTokenFile } from aws-sdk/credential-providers; const s3 new S3Client({ region: process.env.AWS_REGION ?? us-west-2, credentials: fromTokenFile(), }); const result await s3.send(new ListBucketsCommand({})); console.log(result.Buckets);fromTokenFile()依赖的三个变量AWS_WEB_IDENTITY_TOKEN_FILE、AWS_ROLE_ARN、AWS_ROLE_SESSION_NAME。如果 web identity 令牌已在内存中而不是磁盘文件改用fromWebToken()。IAM Identity CenterSSOfromSSO()fromSSO()面向 profile 中直接包含 IAM Identity Center / AWS SSO 设置的情况。先用 AWS CLI 创建 SSO profileaws configure sso示例 profile[profile my-sso-profile] sso_account_id 012345678901 sso_region us-east-1 sso_role_name SampleRole sso_start_url https://d-abc123.awsapps.com/start region us-east-1然后显式使用import { STSClient, GetCallerIdentityCommand } from aws-sdk/client-sts; import { fromSSO } from aws-sdk/credential-providers; const sts new STSClient({ region: us-east-1, profile: my-sso-profile, credentials: fromSSO({ profile: my-sso-profile }), }); const caller await sts.send(new GetCallerIdentityCommand({})); console.log(caller.Account);维护者文档强调的一条限制fromSSO()只支持直接使用 SSO 凭证的 profile如果 profile 还要假设一个由 SSO 派生的其他角色应改用fromIni()它能处理source_profile/credential_source/ SSO 支撑 profile 组合出的 assume-role 链。需要清理本地 SSO 会话时aws sso logout浏览器与移动端Cognito 身份池浏览器或移动端代码需要从身份池换取临时 AWS 凭证时用fromCognitoIdentityPool()import { S3Client, ListObjectsV2Command } from aws-sdk/client-s3; import { fromCognitoIdentityPool } from aws-sdk/credential-providers; const s3 new S3Client({ region: us-east-1, credentials: fromCognitoIdentityPool({ clientConfig: { region: us-east-1 }, identityPoolId: us-east-1:1699ebc0-7900-4099-b910-2df94f52a030, logins: { cognito-idp.us-east-1.amazonaws.com/us-east-1_Example: idToken, }, }), }); const objects await s3.send( new ListObjectsV2Command({ Bucket: example-bucket, MaxKeys: 10, }), ); console.log(objects.Contents);logins的键是 Cognito User Pool 的 issuer值是登录后的 ID token——它把用户身份与 AWS 身份池关联起来。维护者文档指出的缓存行为fromCognitoIdentityPool()内部缓存GetId结果但不缓存GetCredentialsForIdentity结果。如果你已经持有 CognitoIdentityId直接用fromCognitoIdentity()更简洁。身份池与 User Pool 的配套服务客户端可分别参考 cognito-identity 文档和 cognito-identity-provider 文档。客户端构造器之外用默认链预签名场景fromNodeProviderChain()在“辅助函数需要直接拿凭证”时特别有用典型例子是 S3 预签名 URLimport { S3Client, PutObjectCommand } from aws-sdk/client-s3; import { getSignedUrl } from aws-sdk/s3-request-presigner; import { fromNodeProviderChain } from aws-sdk/credential-providers; const credentials fromNodeProviderChain(); const s3 new S3Client({ region: process.env.AWS_REGION ?? us-east-1, credentials, }); const url await getSignedUrl( s3, new PutObjectCommand({ Bucket: example-bucket, Key: uploads/example.txt, }), { expiresIn: 900 }, ); console.log(url);预签名流程创建客户端 → 构造命令 →getSignedUrl的完整细节见 s3-request-presigner 文档。其余可用 provider 一览文档还列出五个按需使用的 providerfromProcess()从共享 AWS 配置 / 凭证文件中读取credential_process执行外部命令获取凭证fromContainerMetadata()从 ECS 任务元数据端点读取凭证fromInstanceMetadata()从 EC2 实例元数据服务读取凭证fromWebToken()使用内存中的 web identity 令牌而非读取令牌文件createCredentialChain()把多个 provider 或自定义异步凭证函数组合成一条链。常见陷阱Gotchas清单维护者文档总结的八条经验逐条对应真实排障场景Node.js 中不要画蛇添足除非确实需要显式 provider不要给客户端加credentials: fromNodeProviderChain()——客户端默认已经在用这条链。两个共享文件不合并~/.aws/credentials与~/.aws/config中的同名 profile 不会合并凭证文件的版本优先。clientConfig的作用域是内部客户端provider 的clientConfig作用于用来解析凭证的内部 STS / SSO / Cognito 客户端设置clientConfig.region可能覆盖所选 profile 中的 region 值。fromIni()要求合法共享配置语法它可以处理source_profile、credential_source、SSO 支撑 profile 与 MFA但 profile 数据必须是有效的 AWS 共享配置格式。fromTokenFile()双要素缺一不可既要 web identity 令牌文件也要 role ARN。fromSSO()仅限直接 SSO profileSSO profile 参与更大 assume-role 链时用fromIni()。元数据 provider 只属于 AWS 运行环境fromContainerMetadata()与fromInstanceMetadata()是给 ECS / EC2 用的不适用于本地开发笔记本。临时凭证的自动刷新规则当凭证对象包含expiration且剩余有效期低于五分钟时凭证 provider 会触发刷新——这解释了为什么基于 provider 的临时凭证无需手写刷新循环。选型速查运行环境 / 需求推荐 providerNode.js凭证已配置好什么都不传默认链非默认 profile / assume-role profilefromIni()只认环境变量、缺失即失败fromEnv()代码里动态 assume rolefromTemporaryCredentials()K8s / EKS IRSA 令牌文件fromTokenFile()内存中的 OIDC 令牌fromWebToken()IAM Identity Center 直接 SSO profilefromSSO()浏览器 / 移动端身份池fromCognitoIdentityPool()已有 IdentityIdfromCognitoIdentity()ECS / EC2 元数据fromContainerMetadata()/fromInstanceMetadata()多来源组合createCredentialChain()赞分享【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载上一篇Phoenix 前端性能优化用 Promise 链式嵌套请求消除服务端 Waterfall下一篇Sentry2视觉传感器高级调参指南ROI区域、参数组与识别数量调优技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考