@growth-labs/conformance

中文文档
0.19.0发布于 2026/11/06TypeScriptES Module近 30 天下载 6656

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

中文使用文档
文档目录9 节
  1. 缓存安全性
  2. 已建工人的路线
  3. 安装
  4. 基本用途
  5. 部署端点适配器
  6. 共享信头政策
  7. 分析标记来源 (@ growth-labs/analysis)
  8. 固定命令
  9. 证据形状

@ 增长栏/ 合规

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

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

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

缓存安全性

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.missingA. 公众的反应 与 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),并返回结果作为符合性结果.

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以其他方式获取的答复.

安装

pnpm add @growth-labs/conformance

基本用途

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 文物文件 和工人把文件捆起来 适配器读取 预建的文物在 模块载荷(不是每个请求)并服务于:

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合同:

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只需要 这些起源,而不是逐一递减的散列:

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 页眉 :

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的结果.

固定命令

根回波曝光:

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 共发布 25 个版本,首次发布于 2026/07/16;过去 12 个月发布了 25 个版本。

版本发布日期距今
0.19.0latest2026/11/0611 天前
0.18.02026/10/2523 天前
0.17.02026/10/1829 天前
0.16.02026/10/081 个月前
0.15.02026/10/081 个月前
0.14.12026/09/201 个月前

关于 @growth-labs/conformance 的常见问题

@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 和提交记录判断。