# @growth-labs/conformance 中文文档

规范地址：https://npmcn.com/package/%40growth-labs/conformance/

版本：0\.19\.0
npm 元数据更新时间：2026-11-05T18:59:11.673Z
中文译文更新时间：2026-11-17T04:16:21.380Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40growth-labs/conformance
原文对照：https://npmcn.com/package/%40growth-labs/conformance/?lang=original

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

- 包体积（解压后）：622 kB，75 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：astro ^6\.0\.0 \|\| ^7\.1\.0，miniflare ^4\.20260301\.1
- 首次发布：2026-07-16T00:14:06.329Z
- 最新版本发布：2026-11-05T18:59:11.480Z
- 近 30 天下载量：6656（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

可重复使用的Growth Labs网站的机队出版物兼容性工具:标题、缓存、元数据、结构数据、图像、出版物表面和证据捆绑.

## 安装

```sh
npm install @growth-labs/conformance
```

也可以使用：`pnpm add @growth-labs/conformance`、`yarn add @growth-labs/conformance`、`bun add @growth-labs/conformance`

## README

# @ 增长栏/ 合规

为增长实验室网站提供可重复使用的出版物兼容性利用。 它能验证 每一地点的固定装置和提供机器可分辨的证据包供制作, 缓存、 安全信头、 元数据、 结构数据、 图像、 发布 表面,发现资格,和建立证据.

这个包被站点和CI工作所消耗. 这不是中央舰队 运行时间和它不获取、变异、部署或储存舰队状态.

公共或爬行器固定装置可明确批准范围内含样式 `expected.publicInlineStyles: { attributes: true, elements: true }`两种布尔 需要; 每项 `true` 需要相应的 `style-src-attr` 或者说 `style-src-elem 'unsafe-inline'` 实际执行的CSP中的补助。 缺席或 `false` 保留现有的严格/属性库存验证。 本合同 不允许私人受众、同时免收属性和 库存接收,或脚本中不安全的内入,默认弧,或无范围样式弧.

## 缓存安全性

```ts
import {
    applyPrivateNoStore,
    assertSafeEntrypointCacheConfiguration,
    evaluateCacheSafety,
    scanRequestStateLeaks,
} from '@growth-labs/conformance/cache-safety'
```

`assertSafeEntrypointCacheConfiguration(finalWranglerConfig)` 验证未知 与 Zod 输入,并丢入不安全或错误的部署缓存设置. 全局/ 默认切入点仍然未标记; 只有输入 `PublicPages` 劳动者 导出可选择使用,而不进行交叉版本再利用。 缓存密钥和工人导出 键很严格;不相关的Wrangler字段和非工作选项被保存. 终极环境控制仍然被禁止。 校验器不突变输入 .

缓存- 安全合同保留默认网关, 需要明确 当公共 HTML 缓存启用时, 仅免费命名的 PublicPages 安全合同, 并验证一个非公共的、无副作用的内饰 带有明确的转发标题许可列表,并证明 HIT 仍然执行 外部网关副作用. `applyPrivateNoStore()` 写入完整 缓存控制/CDN-缓存控制/ Cloudflare-CDN-缓存控制 三进制并移除 瓦里来的饼干.

寄出缓存证据失败 `cache.evidence.missing`A. 公众的反应 与 `Set-Cookie` 除非它装满了三胞胎 否则失败了. `Vary: Cookie` 总是失败——即使与私人三胞胎在一起——因为 Cookie 差异不是 部分支持的合同; 在私人响应标记后删除.

机身扫描仪接受受控请求状态的监视器,并探测到它们 字形,URI,JSON,和 Base64 形式. 它的收受只暴露于国家类别 和编码,绝不是原始的. `cacheSafetyLiveResultSchema` 验证 设定的结果.

## 已建工人的路线

`runWorkerRoutes()` (传教士) `@growth-labs/conformance/worker-routes`只有节点,需要 选项对等点 `miniflare`给建筑工人穿靴子 `dist/server` 在微小的墙上 已承诺的D1固定,并要求出版物必须回答路线问题。 它声称地位, `<title>`、犬科、JSON-LD类型和 `og:image` (和内容类型和 feed, sitemap and robots.txt),并返回结果作为符合性结果.

```ts
import { defaultRoutes, formatRouteReport } from '@growth-labs/conformance'
import { runWorkerRoutes } from '@growth-labs/conformance/worker-routes'

const report = await runWorkerRoutes({
    site: 'megaprojects',
    origin: 'https://megaprojects.pub',
    serverDir: new URL('../dist/server/', import.meta.url).pathname,
    bindings: { SITE_URL: 'https://megaprojects.pub' },
    d1: {
        SITE_DB: {
            migrationsDir: 'migrations', // the site's own migrations, applied in file-name order
            sql: readFileSync('tests/fixtures/routes.sql', 'utf8'), // optional; one statement per line
            seed: async (db) => {}, // optional; seed through the app's code, e.g. the CMS engine
        },
    },
    stubServices: ['ASSETS', 'AUTH'], // answer 503 unless `serviceBindings` supplies one
    routes: defaultRoutes({ article: '/articles/newest', video: '/videos/first' }),
})
if (report.status === 'fail') throw new Error(formatRouteReport(report))
```

查找代码 : `route.status.unexpected` (单位:500) `/` 是这个,从身体开始 证据, `route.content_type.unexpected`, (中文(简体) ), `route.body.expected_missing`, (中文(简体) ), `route.title.missing`, (中文(简体) ), `route.canonical.missing`, (中文(简体) ), `route.canonical.mismatch`, (中文(简体) ), `route.structured_data.type_missing`, (中文(简体) ), `route.og_image.missing`, (中文(简体) ), `route.fetch.failed`。一个路由 spec 可以覆盖任何期望 (单位:千美元)`status` 可能是一个列表, `jsonLdTypes` 条目可能是备选条目)。 纯度的一半 (单位:千美元)`evaluateRoute`, (中文(简体) ), `buildRouteReport`以其他方式获取的答复.

## 安装

```bash
pnpm add @growth-labs/conformance
```

## 基本用途

```ts
import { runFleetConformance, runSiteConformance } from '@growth-labs/conformance'

const fixture = {
    id: 'fronts:article:public',
    site: 'fronts',
    environment: 'production',
    url: 'https://fronts.co/example',
    renderMode: 'ssr',
    audience: 'public',
    response: {
        status: 200,
        headers: {
            'content-security-policy': "default-src 'self'; script-src 'self' 'nonce-runtime'",
            'strict-transport-security': 'max-age=31536000',
            'cross-origin-opener-policy': 'same-origin',
            'cross-origin-resource-policy': 'same-origin',
            'x-frame-options': 'DENY',
            'x-content-type-options': 'nosniff',
            'referrer-policy': 'strict-origin-when-cross-origin',
            'permissions-policy': 'camera=(), microphone=(), geolocation=()',
            'cache-control': 'public, max-age=0, s-maxage=300',
        },
        html: '<!doctype html>...',
    },
    expected: {
        canonicalUrl: 'https://fronts.co/example',
        schemaTypes: ['NewsArticle'],
        discoverEligible: true,
        framePolicy: {
            ancestors: ["'none'"],
            legacyHeader: 'DENY',
        },
    },
    publicationSurfaces: [
        { name: 'sitemap', status: 'present', httpStatus: 200, bodyBytes: 1024 },
        { name: 'robots', status: 'present', httpStatus: 200, bodyBytes: 256 },
        { name: 'feed', status: 'na', capabilityBoundary: 'No editorial feed', evidence: 'site type' },
    ],
    cacheVariants: [
        { audience: 'public', cacheKey: 'fronts:public:/example' },
        { audience: 'crawler', cacheKey: 'fronts:crawler:/example' },
    ],
    cacheSafety: {
        defaultGatewayCacheEnabled: false,
        publicHtmlAllowlist: [],
        inner: {
            publiclyRoutable: false,
            forwardedHeaders: ['accept-language'],
            allowedForwardedHeaders: ['accept-language'],
            sideEffects: false,
        },
        gateway: { hitRunsSideEffects: true },
        response: {
            personalized: false,
            headers: { 'cache-control': 'public, s-maxage=300' },
            body: '<!doctype html>...',
            sentinels: [],
        },
    },
    securityReceipts: {
        functionalProbes: [
            { name: 'oauth', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'media', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'images', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'analytics', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'embeds', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'error-pages', status: 'pass', evidence: 'sanitized consumer probe receipt' },
        ],
        cspReports: [
            {
                name: 'csp-report-canary',
                status: 'pass',
                endpoint: 'consumer-owned-report-endpoint',
                evidence: 'sanitized CSP report or blocked-canary receipt',
            },
        ],
        inlineStyleAttributes: {
            commitSha: 'bd39d718f6a5b0df9a249e11638a8b430050941e',
            occurrenceCount: 4,
            evidence: {
                tool: 'platform-foundations:inline-style-inventory@1',
                outputHash: 'sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
            },
        },
    },
    buildEvidence: {
        commitSha: 'bd39d718f6a5b0df9a249e11638a8b430050941e',
        packageVersions: { '@growth-labs/conformance': '0.6.0', '@growth-labs/seo': '0.9.0' },
        staticHeaderPolicy: true,
        ssrHeaderPolicy: true,
    },
}

const siteBundle = runSiteConformance(fixture)
const fleetBundle = runFleetConformance([fixture])
```

## 部署端点适配器

消费者拥有这条路 符合礼仪的艺术品 和Cloudflare `[version_metadata]` 装订。 CI/建设探险台阶运行 `runSiteConformance()`,将结果序列化为 JSON 文物文件 和工人把文件捆起来 适配器读取 预建的文物在 模块载荷(不是每个请求)并服务于:

```ts
import artifact from './conformance-artifact.json' with { type: 'json' }
import { initConformanceEndpoint } from '@growth-labs/conformance/endpoint'

// Artifact produced by the CI probe step before deployment.
// Static import: a missing conformance-artifact.json is a build-time error —
// the Worker never starts if the artifact is absent.
// Artifact is parsed, schema-stripped, bounded, and serialized ONCE here.
const handler = initConformanceEndpoint(artifact, 'fronts')

// src/pages/.well-known/growth-labs-conformance.json.ts
export function GET({ locals, request }) {
    return handler.handle({
        method: request.method,
        versionMetadata: locals.runtime.env.CF_VERSION_METADATA,
    })
}

export const HEAD = GET
```

`initConformanceEndpoint` 剖析出文物,与v2相对验证 计划,检查 `environment: 'production'` 和预期网站,要求 `buildEvidence.commitSha` (小于40-特征六)和 `buildEvidence.generatedAt` (时间区合格ISO-8601日期时间),以及 序列化了一次图案的字节。 仅按请求处理 验证方法并进行比较 `versionMetadata.tag` 与被烧死的人作对 SHA——没有I/O,没有被探测器执行,没有被重新序列化. 失踪/畸形 文物和错误的站点/环境产生一个总是返回503的处理器. 适配器从不读取或序列化环境绑定,请求标题, Cloudflare版本ID, Cloudflare版本时间戳, 内部例外,或 字段。 它不执行高压秘密 检测: 已记录的自由形式字符串, 如查找信件、 查找 证据、补救文本和收据证据保持不变,属于 消费者的消毒责任.

## 共享信头政策

使用 `buildSharedPublicationHeaders()` 当一个网站想要软件包拥有时 用于安全部门改革和静态反应头的基线。 关于释放物的天体站点 支助 `security.csp` 应让Astro拥有每道散列CSP并保留 剩下的共享标题。 包对等合同仍然是庄园的 可选Astro 6合同:

```ts
import {
    buildAstroCspConfig,
    buildSharedPublicationHeaders,
} from '@growth-labs/conformance/policy'

const csp = buildAstroCspConfig({
    scriptSources: ['https://challenges.cloudflare.com'],
    styleSources: ['https://fonts.googleapis.com'],
})

const headers = buildSharedPublicationHeaders({
    renderMode: 'ssr',
    audience: 'public',
    contentSecurityPolicy: false,
    markdownTwinUrl: 'https://example.com/article.md',
})
```

### 分析标记来源 (@ growth-labs/analysis)

启用 `@growth-labs/analytics` 外部标签必须添加标签' 确切的来源 `SecurityHeadersConfig` 允许列表( 相同 ) 窗体作为以上示例——脚本主机没有通配符。 两个标签都是 外部 `<script src>` 没有线性靴子,所以基于散列的CSP只需要 这些起源,而不是逐一递减的散列:

```ts
const csp = buildAstroCspConfig({
    scriptSources: [
        'https://static.cloudflareinsights.com', // Cloudflare Web Analytics beacon (cookieless)
        'https://www.googletagmanager.com',      // GA4 gtag.js loader (consent-gated)
    ],
    connectSources: [
        'https://cloudflareinsights.com',        // CWA RUM upload
        'https://www.google-analytics.com',      // GA4 collect
        'https://*.google-analytics.com',
        'https://*.analytics.google.com',
    ],
    imgSources: [
        'https://www.google-analytics.com',      // GA4 pixel fallback
        'https://*.google-analytics.com',
    ],
})
```

仅为网站实际启用的标记添加源( CWA 仅网站省略 GA4起源,反之亦然).

固定默认是上面不可嵌入的政策. 为了一个故意 可嵌入的路径, 声明其确切的响应类别, 并省略一个相冲突 `X-Frame-Options` 页眉 :

```ts
expected: {
    framePolicy: {
        ancestors: ['https://trusted.example'],
        legacyHeader: 'omit',
    },
}
```

被接受的祖先为 `'none'`, (中文(简体) ), `'self'`, (中文(简体) ), `https:`和确切的HTTPS起源; 通配符,路径,证书,查询字符串,和片段都被拒绝. `DENY` 仅使用 `'none'`,以及 `SAMEORIGIN` 仅使用 `'self'`宽 嵌入式政策必须使用 `legacyHeader: 'omit'` 避免矛盾 浏览器行为.

天体6号 `security.csp` 无法代表属性范围样式资源。 如果有的话 路由仍然发送 HTML `style` 属性,保留天体本地化帮助 故障关闭,并使用 `style-src-attr` 加减 已验证 `inlineStyleAttributes` 在符合性固定的接收。 这个 接收需要精确的 小写 40 字符构建 承诺 SHA,一个正数 发生数、版本扫描仪身份和小写SHA-256 其机器输出的散列内容。 同一收据必须在 遵守规定及其承诺必须相符 `buildEvidence.commitSha`选择 使用内置式的备忘作为通用相容性修补.

政策发布CSP,HSTS,帧保护,MIME嗅出保护, COOP、CORP、裁判员政策、权限政策、缓存语义和可选 标记下双 `Link` 元数据。 私人受众使用 `private, no-store`· ; 公共 SSR 使用短的共享- cache 语义; 公共静态表面变长 共享缓存语义.

HSTS 默认为 `max-age=31536000` 只有这个 添加 `includeSubDomains` 财务报告和审定财务报表 `preload` 结束 `strictTransportSecurity: { includeSubDomains: true, preload: true }` 只有在消费者单独核实了完整的主机库存之后,才能 执行HTTPS. COOP 默认为 `same-origin` 和CORP 默认为 `same-origin`消费者只有在经过验证的 OAuth 弹出时才能超过, 或嵌入式制约需要宽松的政策,收据证明 执行的CSP的结果.

## 固定命令

根回波曝光:

```bash
pnpm run conformance:test-fixtures
pnpm run conformance:verify-schema
```

定点命令证明所需的负定出错 稳定查找代码 :

-   `csp-unsafe-inline`
-   `missing-coop`
-   `missing-corp`
-   `hsts-below-one-year`
-   `csp-wildcard-default-src`
-   `csp-unsafe-eval`
-   `csp-inline-executable-without-nonce-or-hash`
-   `conflicting-duplicate-security-header`
-   `missing-functional-probe-receipt`
-   `missing-csp-report-receipt`
-   `failed-csp-report-receipt`
-   `headers-static-only-while-ssr-missing`
-   `undeclared-na`
-   `stringified-is-accessible-for-free`
-   `video-object-date-only-upload-date`
-   `missing-image-dimensions`
-   `hero-under-1200px`
-   `missing-max-image-preview-large`
-   `crawler-public-cache-key-collision`
-   `runtime-canonical-override-not-applied`
-   `llms-runtime-static-shadow`
-   `default-entrypoint-cache-enabled`
-   `public-html-without-named-renderer`
-   `named-renderer-not-free-only`
-   `stored-member-response`
-   `stored-crawler-body-response`
-   `stored-set-cookie-response`
-   `raw-credential-forwarded-to-inner`
-   `cached-body-request-state-leak`
-   `gateway-hit-side-effects-bypassed`
-   `personalized-public-response`
-   `public-set-cookie-response`
-   `vary-cookie-response`

## 证据形状

`runSiteConformance()` 返回 a `SiteEvidenceBundle`· ; `runFleetConformance()` 返回 a `FleetEvidenceBundle`。二者均通过导出 Zod 计划验证 并携带 `schemaVersion: "growth-labs.conformance.v2"` 这样下游的工作就可以 在不依赖控制台文本的情况下分析它们.

Schema v2 添加 `securityReceipts` 给固定装置和现场证据包 现有 v1 固定装置必须添加明确的功能测试收据,用于 `oauth`, (中文(简体) ), `media`, (中文(简体) ), `images`, (中文(简体) ), `analytics`, (中文(简体) ), `embeds`,以及 `error-pages`,加上至少一个经过的 CSP 报告/收到通知。 包裹本身不执行活探测器; 消费者CI提供消毒通行证/故障/NA收据.

## 常见问题

### @growth-labs/conformance 是什么？

可重复使用的Growth Labs网站的机队出版物兼容性工具:标题、缓存、元数据、结构数据、图像、出版物表面和证据捆绑\.

### 如何安装 @growth-labs/conformance？

在项目目录运行 npm install @growth-labs/conformance，或使用 pnpm add / yarn add / bun add。

### @growth-labs/conformance 支持 TypeScript 吗？

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

### @growth-labs/conformance 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @growth-labs/conformance 可以商用吗？

@growth-labs/conformance 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @growth-labs/conformance 的下载量有多少？

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

### @growth-labs/conformance 还在维护吗？

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

