specification.website Well-Known UR详解12个/.well-known/文件每个网站都应知道的标准路径【免费下载链接】specification.websiteWebsite specification — HTML, accessibility, security, SEO, agent-readiness. Platform-agnostic, sourced, MIT.项目地址: https://gitcode.com/gh_mirrors/sp/specification.websitespecification.website 是一个开源的 Web 规范站点覆盖 HTML 基础、可访问性、安全、SEO 与 Agent 就绪等主题。本文聚焦其中最容易被忽略的一章——Well-Known URIs12 个/.well-known/标准文件帮助浏览器、App、密码管理器和 AI 代理按图索骥地找到你的网站能力。什么是 Well-Known URI固定路径的能力公告栏Well-Known URI是一种约定把一个资源放在https://你的域名/.well-known/某名称这个固定路径下由 RFC 8615 定义并保留该前缀。它的价值在于三点可发现性浏览器、密码管理器、移动系统、联邦服务器无需任何配置就知道去哪里找你的能力声明互操作性Mastodon、Apple、Google、OpenID Connect 等生态靠标准路径跨千万网站协同工作️稳定性元数据统一收进/.well-known/命名空间不会和你的业务路由撞车。需要记住的关键点/.well-known/是URL 命名空间不是磁盘目录。有些是静态 JSON 文件有些是重定向或查询接口——客户端只关心路径和响应。⚠️ 另外允许使用的名称不是任起的IANA 维护着一个公开的注册表未注册的路径名可能未来被分配给别人。12 个 /.well-known/ 文件完整清单以下 12 个条目全部来自项目的 well-known 章节src/content/spec/well-known/前 4 个适用于所有网站其余按需启用#标准路径作用谁在消费适用场景1总览RFC 8615 原则通用规则与常见错误所有人✅ 必读2/.well-known/change-password302 重定向到改密页1Password、Bitwarden 等密码管理器有用户账号3/.well-known/webauthn声明 Passkey 可跨哪些域名使用Chrome、Safari、Firefox多域名共用 Passkey4/.well-known/api-catalog机器可读的资源目录LinksetAI 代理、爬虫所有想被 Agent 读懂的站5/.well-known/webfinger把用户域名解析成真实 URLMastodon、PeerTube 等联邦平台联邦社交账号6/.well-known/apple-app-site-association授权 iOS/macOS App 处理你的链接Apple通用链接、密码共享有 Apple 平台 App7/.well-known/assetlinks.json证明 Android App 与域名同属一方GoogleApp Links有 Android App8/.well-known/nodeinfo联邦服务器的自我介绍联邦统计站、管理员工具联邦服务器9/.well-known/openid-configurationOIDC 身份提供者的发现文档Auth0、Keycloak 等客户端你是 OIDC 提供商10/.well-known/oauth-authorization-serverOAuth 2.0 授权服务器元数据RFC 8414OAuth 客户端你运行授权服务器11/.well-known/oauth-protected-resourceOAuth 保护资源元数据RFC 9728OAuth/MCP 客户端你暴露受保护 API12/.well-known/traffic-advice控制浏览器预取代理的流量比例Chrome 私有预取代理希望拒绝/限流预取账号与安全类change-password 与 webauthnchange-password一行重定向省下无数迷路这是一条固定 URL通过302 重定向指向你的真实改密页面由 W3C Web 应用安全工作组定义。当密码管理器检测到弱密码或泄露凭据时会探测这个路径——通了更改密码按钮就能一键直达。细节要点见 change-password.md目标是改密码已知凭据的用户不是重置密码忘记密码流程两者别搞混无登录态访问时应重定向到登录页再跳回改密页返回 404 等于告诉密码管理器不支持此功能——没有账号系统的静态站干脆不要实现。webauthn一套 Passkey 通行多个域名Passkey 默认绑定单一 RP ID可注册域名。当一家公司运营example.com、example.co.uk等多个域名时/.well-known/webauthn声明哪些源可以共用同一个 RP ID让用户一次注册、处处登录WebAuthn Level 3 的 Related Origin Requests。这是一个纯静态 JSON 白名单由浏览器强制执行无共享密钥、无跳转舞蹈。移动端互操作AASA 与 assetlinks.json这两个文件是 Apple 与 Google 各自版本的App 与域名是同一家人声明Appleapple-app-site-associationAASA。路径不带.json后缀、必须直接返回 200、Content-Type 必须是application/json——返回重定向会被 Apple 视为硬性失败。它支撑通用链接点链接直开 App、Shared Web Credentials网页与 App 密码互填等能力见 apple-app-site-association.md。Googleassetlinks.jsonDigital Asset Links 协议。路径必须带.json后缀。要列出所有发布变体的 SHA-256 签名证书指纹——最常踩的坑是漏掉 Play App Signing 的实际签名证书只填了上传密钥。联邦网络类webfinger 与 nodeinfowebfinger把handledomain翻译成人话WebFingerRFC 7033是联邦世界的114 查号台客户端带着resourceacct:joostexample.com发 GET 请求服务器返回 JSON 描述该账号的真实 URL 和别名。你在 Mastodon 里输入alicemastodon.example就能找到 Alice靠的就是它。高频错误见 webfinger.md答错主机acct:右侧的域名必须就是提供 WebFinger 的主机放在social.子域上会直接让联邦失联Content-Type 必须是application/jrdjson返回application/json会出问题用户存在但私有和用户不存在应返回一致的行为避免泄露账号存在性。nodeinfo联邦服务器的自我介绍NodeInfo 是两步发现机制/.well-known/nodeinfo先返回一组指向版本化文档如/nodeinfo/2.1的链接文档里再描述服务器运行的软件、版本、协议和用户统计。它源自 Diaspora如今被 Mastodon、PeerTube、Misskey、Lemmy 等几乎所有 Fediverse 平台采用。⚠️ 常见错误是直接把 NodeInfo 文档从 well-known 路径吐出去——这个 URI 只是指针正文住在别处。OAuth 身份三件套从零配置到自动发现OAuth 生态是 Well-Known URIs 最精彩的示范多个文件互相引用客户端可以无配置一路跟进。oauth-protected-resourceRFC 9728受保护 API 声明我接受谁签发的 token。客户端收到 401 时WWW-Authenticate头会直接附上这份文档的地址oauth-authorization-serverRFC 8414授权服务器自述端点、支持的 scope 与密钥地址jwks_uriopenid-configurationOpenID Connect 提供商版本字段与上一份几乎相同但面向 OIDC发行id_token。最容易翻车的细节issuer 带路径时两者拼接规则相反——RFC 8414 把.well-known/...插入路径之前/tenant1→/.well-known/oauth-authorization-server/tenant1而 OIDC 把它追加在后。多租户部署写错这里客户端就永远找不到你。另一个硬性规则issuer值必须与客户端使用的 URL逐字符一致含 scheme、无末尾斜杠这是invalid issuer 报错的头号原因。面向机器与性能api-catalog 与 traffic-adviceapi-catalog给 AI 代理的站内地图/.well-known/api-catalogRFC 9727是 IETF 正式标准用 Linksetapplication/linksetjson把站点的机器可读资源——sitemaps、llms.txt、OpenAPI 规范、license、RSS——汇成一份目录。虽然名字带 api它收录的远不止 API。发布要点Content-Type 必须是application/linksetjson返回application/json会让严格校验的代理直接跳过配合Link: /.well-known/api-catalog; relapi-catalog响应头做无带外提示的发现目录漂移比没有目录更糟——CI 中应对每个被引用的 URL 做校验。traffic-advice告诉预取代理能不能来/.well-known/traffic-advice让站点向 Chrome 的私有预取代理声明拒绝disallow: true或按比例放行fraction0~1。按 user_agent 匹配最具体的身份优先。这是少见的用 well-known 文件做流量治理的用例。发布 Well-Known URIs 的四条通用规则无论实现哪个文件以下规则全部适用摘自 well-known-overview.md✅HTTPS 规范主机在用户实际访问的主机上提供而不是子域✅精确路径与文件名大小写敏感AASA 无后缀、assetlinks 有后缀别记混✅正确的 Content-Type多数是application/jsonWebFinger 是application/jrdjsonapi-catalog 是application/linksetjson✅放行探测流量CDN、WAF、认证中间件必须放通。藏在登录墙后面的 well-known URI 等于不存在也别按 User-Agent 粗暴封禁。验证方式很简单curl -I https://你的域名/.well-known/名称应返回 200change-password 为 302/303与正确的 Content-Type并在 IANA 注册表中确认该名称已登记。小结/.well-known/是标准的能力发现命名空间由 RFC 8615 保留、IANA 注册表约束命名12 个文件中api-catalog 对所有网站推荐change-password 对有账号的站点几乎零成本其余按需启用记住三条高频坑漏掉开头的小数点写成/well-known/、Content-Type 被框架包成 text/html、让文件落在登录墙后面每个文件的完整是什么 / 为什么 / 怎么实现 / 常见错误 / 验证五段式说明都收录在项目规范目录下如src/content/spec/well-known/配合public/og/spec/well-known/中每个主题的配图可直接用于团队内部培训材料。【免费下载链接】specification.websiteWebsite specification — HTML, accessibility, security, SEO, agent-readiness. Platform-agnostic, sourced, MIT.项目地址: https://gitcode.com/gh_mirrors/sp/specification.website创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考