# @atlaskit/atlassian-context 中文文档

规范地址：https://npmcn.com/package/%40atlaskit/atlassian-context/

版本：2\.0\.0
npm 元数据更新时间：2026-09-24T01:54:36.152Z
中文译文更新时间：2026-11-07T02:31:01.237Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlaskit/atlassian-context
原文对照：https://npmcn.com/package/%40atlaskit/atlassian-context/?lang=original
项目主页：https://bitbucket.org/atlassian/atlassian-frontend-monorepo#readme
源码仓库：https://bitbucket.org/atlassian/atlassian-frontend-monorepo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：143 kB，141 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2024-06-12T11:43:11.116Z
- 最新版本发布：2026-09-24T01:54:35.954Z
- 近 30 天下载量：5597263（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 11 个）

## 中文简介

提供周边特有URL分辨率,并帮助识别产品运行在何种环境.

## 安装

```sh
npm install @atlaskit/atlassian-context
```

也可以使用：`pnpm add @atlaskit/atlassian-context`、`yarn add @atlaskit/atlassian-context`、`bun add @atlaskit/atlassian-context`

## README

# 环境背景库

提供周边特有URL分辨率,并帮助识别产品运行在何种环境.

更多信息,请参见本文最初的考虑: [https://hello.atlassian.net/wiki/spaces/FEDRAMP/pages/2561199256/UI+隔离](https://hello.atlassian.net/wiki/spaces/FEDRAMP/pages/2561199256/UI+Isolation)

## 所有权

2025年,图书馆所有权被划入规范行业. 请联系#帮助-跨界的帮助.

## 安装

```sh
npm install @atlaskit/atlassian-context --save
```

## 先决条件

> **_注:_** 如果在2025年5月以后首次登入图书馆,则跳过这些预先要求。 这些先决条件是原始的 `configure()`, (中文(简体) ), `getATLContextDomain()`, (中文(简体) ), `getATLContextUrl()`,以及 `isFedRamp()` 函数,将在近期内贬值.

为了 `@atlaskit/atlassian-context` 正确工作 `window.ATL_CONTEXT_DOMAIN` 必须是 设置在页面上。 产品必须在窗口上或者调用数据 `configure()`,在 呼叫任何接听\*()电话。 否则 `getATLContextDomain()` 财务报告和审定财务报表 `getATLContextUrl()` 将使用 后退,并可能返回一个未经修正的反应.

如果使用已贬值的 `isFedRamp()` 方法,还 `window.UNSAFE_ATL_CONTEXT_BOUNDARY = 'fedramp-moderate' | 'commercial'` 必须设置在页面上. 否则,你可能会为环境服务 代码与它们无关.

## 设置

> **_注:_** 如果在2025年5月以后首次登入库, 请跳过此设置 。 获取 `window.ATL_CONTEXT_DOMAIN` 财务报告和审定财务报表 `window.UNSAFE_ATL_CONTEXT_BOUNDARY` 仅用于 `configure()`, (中文(简体) ), `getATLContextDomain()`, (中文(简体) ), `getATLContextUrl()`,以及 `isFedRamp()` 函数,将在近期内贬值.

要返回正确的结果, 此图书馆必须关闭 。 它是如何被关闭的 取决于你的服务。 任何Micros服务都可以从 [配置登记](https://bitbucket.org/atlassian/shared-environment-config)任何进一步的帮助, 联系到 [\# 帮助- 配置- 注射器](https://atlassian.enterprise.slack.com/archives/C0611PE6WDU)。 。 。 .

**QQ 警告 : `window.MICROS_PERIMETER` 将替换为 `window.UNSAFE_ATL_CONTEXT_BOUNDARY` 内 未来迭代 - 见 [发生 - 发生 - 发生](https://go.atlassian.com/is-fedramp)。 。 。 .**

-   `window.MICROS_PERIMETER` - 看见没 [发生 - 发生 - 发生](https://go.atlassian.com/is-fedramp) \* 联合国

### 服务器生成的 HTML

_建议_

如果您的服务总是生成静态 HTML, 您可以利用窗口上下文来正确配置 这个图书馆 将这个速度模板片段视为一个实例:

```html
<!-- Assuming your Java service has loaded the appropriate configuration into $domain_config -->

<script nonce="$nonce">
    window.ATL_CONTEXT_DOMAIN = $domain_config.stringify();
</script>

<!-- Assuming your Java service has loaded the micros perimeter into $micros_perimeter.
    NOTE: Only needed if your service uses the isFedRamp function
  -->
<script nonce="nonce">
    window.UNSAFE_ATL_CONTEXT_BOUNDARY = $micros_perimeter.stringify();
</script>
```

如果找到变量, 库将自动关闭此配置 。 如果 不可用配置, 它会使用回落并可能返回未校正的值 .

### 无服务器

_挫折: 这将退缩您的应用性能 。 您的页面不再是没有服务器的,因为它 fedRAMP 配置的要求。 您应该移动到基于服务器的托管 ._

在渲染前,您必须获取数据

```js
import { configure } from '@atlaskit/atlassian-context';

function init(){
  // get the config from globaledge
  const data = await fetch('https://my.backend.api/_config/domains');

  // tell @atlaskit/atlassian-context about it
  configure(data)

  // and only then run other code / render your page
  ReactDOM.render(<YourApp />, element)
}
```

如果您的应用程序是通过 React SSR 实现的, 您应该确保您需要手动操作 援引 `configure()` 函数与提供的数据.

## API 密码

### 配置 ()

_免责声明:_ 这一点无需用于: `isFedrampModerate()`, (中文(简体) ), `isIsolatedCloud()`, (中文(简体) ), `isolatedCloudDomain()`, (中文(简体) ), `isolationContextId()`, (中文(简体) ), `getDomainInContext(...)`,以及 `getUrlForDomainInContext(...)` 函数.

收集数据,并存储在 `window.ATL_CONTEXT_DOMAIN` 用于以后使用.

### 获取ATL 连接域( )

_免责声明:_ 请使用 `getDomainInContext(subdomain, environment)` 而不是这一职能,因为这一职能的贬值过程将在近期内开始.

返回给定的Atlassian服务域 。 它依赖 `window.ATL_CONTEXT_DOMAIN` 为: 在页面上显示,以防万一 `window.ATL_CONTEXT_DOMAIN` 未定义 `getATLContextDomain()` 将 尝试从硬码域列表中获取该值, 无法更新 。 这个 倒计时依赖 `window.UNSAFE_ATL_CONTEXT_BOUNDARY` 如果未定义, 则在页面中显示 `getATLContextDomain()` 将回落到非痛苦(商业)值.

```js
import { getATLContextDomain } from '@atlaskit/atlassian-context';

getATLContextDomain('jira'); // jira.atlassian.com OR jira.atlassian-fex.com depending based on environment
getATLContextDomain('confluence'); // confluence.atlassian.com
getATLContextDomain('admin'); // admin.atlassian.com OR admin.atlassian-fex.com
```

### 获取 ATL 康特文本Url ()

_免责声明:_ 请使用 `getUrlForDomainInContext(subdomain, environment)` 而不是这一职能,因为这一职能的贬值过程将在近期内开始.

返回全部内容 `url` 提供阿特拉斯服务。 以为基础 `getATLContextDomain`,这个 依赖 `window.ATL_CONTEXT_DOMAIN` 在页上显示,否则 `getATLContextDomain` 将 尝试从硬码域列表中获取该值, 无法更新 可能回落到非犯罪(商业)价值.

`getATLContextUrl()` 检测浏览器协议(http/https)并将其应用到 `domain`。 。 。 .

```js
import { getATLContextUrl } from '@atlaskit/atlassian-context';

getATLContextUrl('jira'); // https://jira.atlassian.com OR https://jira.atlassian-fex.com depending based on environment
getATLContextUrl('confluence'); // https://confluence.atlassian.com
getATLContextUrl('admin'); // https://admin.atlassian.com OR https://admin.atlassian-fex.com
```

### 是FedRamp () (中文(简体) )

_免责声明:_ 请使用 `isFedrampModerate()` 而不是这一职能,因为这一职能的贬值过程将在近期内开始.

_注意:考虑替代办法_ 不建议使用这一功能作为长期解决办法,因为 它创造了一个假设,除了FedRAMP Medrate之外,没有其他孤立的环境. 你个 鼓励考虑其他解决办法,例如Statsig或环境配置 不需要在您的代码特性和 FedRAMP 环境之间建立严格的依赖性 见 [发生 - 发生 - 发生](https://go.atlassian.com/is-fedramp)

返回服务是否部署在联邦RAMP边界. `isFedRamp()` 依赖 `window.UNSAFE_ATL_CONTEXT_BOUNDARY` 在页面上显示,以防 `window.UNSAFE_ATL_CONTEXT_BOUNDARY` 它将试图根据 网站域名,最终折回为假.

```js
import { isFedRamp } from '@atlaskit/atlassian-context';

if (isFedRamp()) {
    // your specific logic here
}
```

### 是Fedramp 模版( )

如果当前周边位于 FedRAMP-Modelate 中, 返回真实性 .

### 孤立的云( )

如果当前周边处于孤立云中, 返回真实值 .

### 孤立的 Cloud 域( )

返回当前 `ic_domain`。如果目前的周边不是L2 IC(例如,目前的Federamp-moderate或正版商业),则返回未定义.

### 孤立 ContextId ()

返回当前孤立上下文标识符( ex: `ic-123`) (中文(简体) ). 如果目前的周界不是L2 IC(例如,周界是联邦制-中度或常规商业),则返回未定义.

### 获得Domain InContext( 子域, 环境)

返回给定的Atlassian服务或体验的完整域名(包括支持隔离云).

重要: 注意库目前不保证请求域存在! 据推测,当一个用户请求一个特定服务的全部域名时,他们已经知道域名的存在.

参数:

-   `subdomain` 是需要的参数。 这应该是要求获得全部域名的服务或Atlassian的经验.
    
-   `environment` 是需要的参数。 这应该是 `dev`, (中文(简体) ), `staging`,或 `prod`。 。 。 .
    

#### 非孤云细说:

对于非孤立的云(如Federamp-moderate和正则商业),将使用周边和环境值来创建并返回预期域.

例外保存于 [全域覆盖](https://npmcn.com/package/%40atlaskit/atlassian-context/src/common/constants/domains.tsx) 定义。 如果您需要URL映射, 那么您应该添加一个条目到 `domains.tsx`。 。 。 .

实例: 当在联邦中调时:

```js
import { getDomainInContext } from '@atlaskit/atlassian-context';

getDomainInContext('id', 'staging') // returns "id.stg.atlassian-us-gov-mod.com" (id has a full domain override)
getDomainInContext('analytics', 'staging') // returns "analytics.atlassian.com" because `analytics` is a non-varying global domain
getDomainInContext('nonexistent-service', 'staging') // returns "nonexistent-service.stg.atlassian-us-gov-mod.com"
```

(非同化)商业召见时:

```js
import { getDomainInContext } from '@atlaskit/atlassian-context';

getDomainInContext('id', 'prod') // returns "id.atlassian.com"
getDomainInContext('analytics', 'prod') // returns "analytics.atlassian.com"
```

#### 孤云细说:

对于绿洲,返回三个域类型之一:一个保留名域,一个命名空间子域名,或者一个Atlassian服务子域名(参见 [RFC (RFC ) (法语)](https://hello.atlassian.net/wiki/spaces/NSC/pages/4352719139/RFC-3+Oasis+Isolation+Context+External+Public+DNS#Atlassian-owned-base-domain-with-domain-based-routing)) (中文(简体) ).

保留的名称和命名空间子域正在临时配置 [准备金 名称映射和地图](https://npmcn.com/package/%40atlaskit/atlassian-context/src/services/generalized-domain-lookup/constants.tsx) 定义。 如果在其中一个类别下注册了一个新名称,请提出PR,以更新相关的映射.

优先级如下: 保留名称模式 > 命名空间模式 > 默认为服务模式.

示例 (同化)商业召见时:

```js
import { getDomainInContext } from '@atlaskit/atlassian-context';

getDomainInContext('id') // returns "id.<icLabel>.<baseDomain>"
getDomainInContext('packages') // returns "packages.atl.<icLabel>.<baseDomain>"
getDomainInContext('new-service') // returns "new-service.services.<icLabel>.<baseDomain>"
```

### 获取 UrlForDomain 连接( 子域, 环境)

通过将当前 URL 方案附加到结果中来返回给定的 Atlassian 服务的全部 url(包括支持隔离云) `getDomainInContext(subdomain, environment)`。 。 。 .

```js
import { getUrlForDomainInContext } from '@atlaskit/atlassian-context';

getUrlForDomainInContext('design', 'staging') // --> returns "https://design.atlassian.com"
```

### 解析器

鉴于用户提供的 URL 边界密钥地图, 返回与当前边界相关的 URL 。 与 `getUrlForDomainInContext(subdomain, environment)`,它从已知的Atlassian子域图案构造一个URL, `resolveProvidedUrlByBoundary` 用于您拥有完全的,任意的URL,每个边界可能完全不同(例如第三方服务端点或自定义后端URL)的情况.

唯一的参数是 `urls`,用于 `URL` 对象。 这个 `default` 键为 **所需经费** 作为保证倒计时;所有特定边界的密钥都是可选的. 有效密钥为 `'isolated-cloud'` | `'fedramp-moderate'` | `'commercial'` | `'default'` (必须)

分辨率命令 :

1.  特定边界密钥( E)`'isolated-cloud'`, (中文(简体) ), `'fedramp-moderate'`,或 `'commercial'`(中文(简体) )
    
2.  `'default'`
    

过 `null` 用于明确返回的边界密钥 `null` 用于该边界(即选择不返回 URL).

> **说明:** URL 值由调用者使用 `new URL(...)`。将无效的 URL 字符串传递到 `new URL()` 将丢出一个 `TypeError` 在此之前 `resolveProvidedUrlByBoundary` 被援引.

```js
import { resolveProvidedUrlByBoundary } from '@atlaskit/atlassian-context/resolve-provided-url-by-boundary';

const url = resolveProvidedUrlByBoundary({
  'isolated-cloud':   new URL('https://ic.example.com'),  // returned in Isolated Cloud
  'fedramp-moderate': null,                                // explicitly no URL in FedRAMP to represent FedRAMP unavailability
  default:            new URL('https://example.com'),      // returned in all other boundaries
});
```

## 常见问题

### @atlaskit/atlassian-context 是什么？

提供周边特有URL分辨率,并帮助识别产品运行在何种环境\.

### 如何安装 @atlaskit/atlassian-context？

在项目目录运行 npm install @atlaskit/atlassian-context，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @atlaskit/atlassian-context 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atlaskit/atlassian-context 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @atlaskit/atlassian-context 可以商用吗？

@atlaskit/atlassian-context 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlaskit/atlassian-context 的下载量有多少？

根据 npm 官方下载统计，@atlaskit/atlassian-context 在 2026/10/07 – 2026/11/05 这 30 天内被下载 5,597,263 次，日均约 186,575 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @atlaskit/atlassian-context 还在维护吗？

最新版本 2\.0\.0 发布于 2026/09/24（1 个月前）；至今共发布 22 个版本，其中过去 12 个月发布了 11 个；首次发布于 2024/06/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。