MDN 2024 内容项目

MDN Web Docs 为从初学者到专业开发者构建 Web 应用的人们提供准确且易于访问的资源。我们的承诺包括维护长期存在的内容，以及记录 Web 平台上的全新功能。

2024 年，MDN 内容团队选择了一些内容领域进行审核和更新，以确保它们在不断发展的 Web 平台上保持有用和相关性。我们关注了那些受欢迎但包含一些过时或不完整内容的议题，并投入时间进行改进、补充和删除过时内容。

这篇博文回顾了我们在 2024 年内容项目中所取得的成就，重点介绍了一些我们精选和推荐的阅读内容，并展望了 2025 年 MDN 的未来。

2024 年 MDN 内容领域

2024 年，我们选择了三个技术类别，它们非常受欢迎，但读者反馈表明需要进行更新。我们专注于 HTTP、MathML 和 Web Manifests。从 2024 年 7 月到 12 月，团队在这些领域进行工作，从多方面提升了质量。下面我们来看看每个部分的变化。

MathML

MathML 是一种基于 XML 的语言，用于在 Web 上描述数学符号。与 SVG 类似，MathML 也可以包含在 HTML 中，并由浏览器渲染，无需插件或库。

\sum_{n = 1}^{+ ∞}

html

<math display="block">
  <munderover>
    <mo>∑</mo>
    <mrow>
      <mi>n</mi>
      <mo>=</mo>
      <mn>1</mn>
    </mrow>
    <mrow>
      <mo>+</mo>
      <mn>∞</mn>
    </mrow>
  </munderover>
</math>

与通常对元素进行分组的 MathML Core 规范不同，MDN 现在在每个 MathML 元素的页面上都详细介绍，并附有示例、使用说明和 BCD（浏览器兼容性数据）。例如，您可以阅读关于 <semantics>、<annotation> 和 <annotation-xml> 元素及其如何帮助注释 MathML 表达式。

就像我们现在用 Markdown 而不是 HTML 来编写这篇博文一样，MathML 通常由数学处理器使用轻量级标记语言（如 LaTeX）生成。为了帮助内容作者，现在所有 MathML 示例都带有注释。例如， $x^{2} + y$ 在 LaTeX 中可以写成 x^{2} + y

html

<math>
  <semantics>
    <mrow>
      <msup>
        <mi>x</mi>
        <mn>2</mn>
      </msup>
      <mo>+</mo>
      <mi>y</mi>
    </mrow>
    <!-- Annotated with LaTeX, a lightweight markup language. -->
    <annotation encoding="application/x-tex">x^{2} + y</annotation>
  </semantics>
</math>

这将使我们能够在未来使用 LaTeX 来编写 MathML，从而使内容作者更容易编写和维护示例。为了充分体会其中的区别，您可以将一些大型示例的完整 MathML 源代码（例如推导二次公式和证明勾股定理）与其 LaTeX 等效项进行比较。

MDN 上的 MathML 文档现在为所有元素提供了可访问性信息。例如，使用 <math> 元素来表示数学内容允许屏幕阅读器读取公式，这使得 MathML 在此类情况下比使用图像或其他格式更好。

此外，所有 MathML 功能现在都有实时示例，因此您可以在浏览器中看到它们的渲染效果。就像 MDN 上其他实时示例一样，您始终可以在右上角点击“播放”按钮在新标签页中交互式地修改代码。

html,
body {
  height: 100%;
}

body {
  display: grid;
  place-items: center;
  font-size: 1.5rem;
}

<math display="block">
  <mrow>
    <mi>x</mi>
    <mo>=</mo>
    <mfrac>
      <mrow>
        <mrow>
          <mo>−</mo>
          <mi>b</mi>
        </mrow>
        <mo>±</mo>
        <msqrt>
          <mrow>
            <msup>
              <mi>b</mi>
              <mn>2</mn>
            </msup>
            <mo>−</mo>
            <mrow>
              <mn>4</mn>
              <mo>⁢</mo>
              <mi>a</mi>
              <mo>⁢</mo>
              <mi>c</mi>
            </mrow>
          </mrow>
        </msqrt>
      </mrow>
      <mrow>
        <mn>2</mn>
        <mo>⁢</mo>
        <mi>a</mi>
      </mrow>
    </mfrac>
  </mrow>
</math>

MDN 不仅记录了 MathML，还使用它来描述 Web 平台的各个部分。例如，JavaScript 方法 Set.difference()、游戏开发中的 CSS 变换函数 transformation functions、3D 碰撞检测 3D collision detection、WebXR 设备 API WebXR Device API，等等。

我们确保 MathML 现在在 MDN 的各个部分都能正确渲染：在段落内和块级别，在大屏幕和小屏幕上，以及在不同的浏览器中。

Manifest（Web 应用清单）

Web 应用清单是一个 JSON 文本文件，提供了 Web 应用的信息。清单最常见的用途是提供浏览器在将渐进式 Web 应用 (PWA) 安装到设备上时所需的信息，例如应用的名称和图标。

json

{
  "name": "HackerWeb",
  "short_name": "HackerWeb",
  "start_url": "/index.html",
  "display": "standalone",
  "background_color": "#ffffff",
  "description": "A readable Hacker News app",
  "icons": [
    {
      "src": "images/icons/homescreen192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}

对于清单内容更新，Dipika 与 Firefox 工程师 Jonathan Almeida 合作，更新了 Firefox 中清单成员的浏览器兼容性数据。更新后的清单 BCD 补充内容现在涵盖了 Firefox 和 Firefox for Android 的兼容性数据，确保了准确且最新的支持信息。MDN、Can I use 和其他网站上的读者现在都能获得关于跨浏览器清单支持的可靠指导。

在内容方面，针对文本、布局和模板修复，该部分进行了多项改进。页面模板现在已得到改进，提高了整个部分的阅读性和一致性。对于每个成员值（例如，"display": "standalone",），都有适当的文本描述，并举例说明了该值可能的使用场景。

使用说明被收集到一个专门的“描述”部分，并且规范中提到的任何 MDN 页面上未包含的注意事项现在都已记录在案。有些页面完全缺少“语法”部分，现在这些空白已经被填补，以便读者能更好地理解如何使用已记录的功能以及一些可能的成员值。

json

/* Boolean values */
"prefer_related_applications": true
"prefer_related_applications": false

这次更新确保了现有内容更加全面和易读，还包含了对类似功能的引用，为开发者提供了更大的灵活性。例如，在 HTML 中使用 prefers-color-scheme 为浅色和深色模式设置不同的 theme_color 值。

html

<meta
  name="theme-color"
  content="#F4E6D8"
  media="(prefers-color-scheme: light)" />
<meta
  name="theme-color"
  content="#5D4037"
  media="(prefers-color-scheme: dark)" />

HTTP 内容更新

HTTP 是 Web 上数据交换的基础协议。它允许浏览器和服务器之间进行通信，也可以用于机器到机器的通信，自动化 API 访问等。在 MDN 上，HTTP 部分有超过 300 页的参考资料，其中大部分是关于 HTTP 标头和响应状态码的。

响应状态码让客户端知道 HTTP 请求的结果（例如 200、404），并在某些情况下提供额外的上下文。MDN 上记录了 61 个状态码，包括常见响应的示例以及对 Web 开发者可能不经常遇到的罕见类型的解释。您甚至可以确保您熟悉 418 (I'm a teapot) 状态码，以防万一。

MDN 上记录了 148 个 HTTP 标头。HTTP 标头是 HTTP 消息中携带元数据、客户端或服务器信息、给接收者的指令等的部分。有些标头有几个子页面，描述了可以通过标头控制的机制，例如内容安全策略 (CSP) 指令，它指示浏览器限制构成网站的代码可以运行的内容，以及权限策略指令，用于请求使用浏览器功能（如位置或麦克风访问）的权限。

MDN 上的 HTTP 指南概述了协议的工作原理，描述了协议从 HTTP/0.9 到当前版本的演变。我们记录了控制 HTTP 交互的各种方法，例如缓存和条件请求，并且我们有关于如何使用和理解协议的指南，从初学者到更高级的主题。这些指南更新的很大一部分意味着在讨论消息格式时，将减少对 HTTP/1.1 的特定引用，因为 HTTP/2 和 HTTP/3 越来越普遍。

http

HEAD /en-US/docs/Web/HTTP HTTP/2
Host: developer.mozilla.org
User-Agent: curl/8.7.1
Accept: */*

* Request completely sent off
HTTP/2 200

总而言之，我们对整个 HTTP 部分所做的更改包括在缺失或太短而无法使用的示例处添加示例，删除过时或废弃的信息，并使所有页面的格式和呈现保持一致。

MDN 上的 HTTP 亮点

更新的一部分包括更新和添加解释客户端-服务器交互的顺序图。我们发现 mermaid 语法对于许多这类图很有用，因为它更容易存储我们以后可能需要更新的图像源。

这些图像存储在 shared-assets 仓库中，这使得我们可以重用图像而不是在源文件中重复它们，并且这些图像更容易编写、阅读、维护，而且看起来也很漂亮！

Like for a regular upload, the first upload of a resource is subject to a race condition: If-None-Match can prevent it.

HTTP 部分中一个有趣的亮点是 Server-Timing 响应头，您可以使用它将服务器指标暴露给客户端。

http

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 123
Date: Fri, 03 Jan 2025 10:41:21 GMT
Server-Timing: custom-metric;dur=123.45;desc="My custom metric"

--- response body ---

根据请求的类型，您可以决定是否要将服务器时序发送到客户端，这些时序在大多数浏览器的开发者工具的网络请求详细信息面板中可见。例如，BBC iPlayer 使用 Server-Timing 标头发送有关服务的性能指标，如下面的“网络 > 时序”面板所示。如果您觉得这很有趣，请务必查看 Performance API 和 Web Performance 文档。

The 'Network > Timings' panel in Firefox developer tools.

对于 HTTP 部分，大多数 BCD 更新涉及提高现有条目的准确性并添加缺失的标头兼容性数据。新增内容包括用于记录服务工作线程脚本请求的 Service-Worker 请求头，以及在 WebSocket 握手中使用的 Sec-Websocket-* 标头。

HTTP 的大部分更新都是针对较旧的功能，但支持信息的准确性对于开发者做出构建决策至关重要。一个例子是 Trailer 兼容性详情，现在反映了浏览器实现。避免在兼容性表中提供误导性信息非常重要，因为它们可能会鼓励人们在应用程序中为实际浏览器支持较差的功能开发功能。

MDN 2024 年其他内容亮点

以下是 2024 年发布的一些有趣文档精选：

新！ CSS 锚点定位文档
新！使用 View Transition API 指南

除了参考文档，我们还在 MDN 博客上撰写了以下主题：

我们还发布了关于以下更改和发布的消息：

MDN 上的新学习体验，将 MDN 课程整合到“学习 Web 开发”中。
推出 MDN HTTP Observatory，用于测试服务器 HTTP 标头配置。
当然，我们还有一个新的社区页面，我们很高兴与大家分享！

Firefox 开发者发布说明

Firefox 发布说明描述了对日常浏览器用户所做的更改。MDN 团队为每个 Firefox 发行版记录了专门针对开发者的发布说明。这意味着在 2024 年，Firefox 版本 122 至 133 都有页面描述了开发者可以定位的每次 Firefox 发行版中的更改。您可以在 Firefox 开发者发布说明页面上找到所有内容。

您可能不知道的是，我们还记录了 Firefox 中的实验性功能。此页面描述了在 Firefox 中实现的功能，但仅通过首选项（尽管配置）可用。您可以在功能发布之前测试即将推出的功能，这非常适合您计划使用实验性技术，或者如果您好奇并希望在 Bugzilla 上提供反馈。

开启 2025 年

团队所从事的内容项目是一次绝佳的学习经历，我们希望我们的读者能从中受益匪浅。如果您想让我们的文档更好，请告诉我们是否还有其他需要关注的领域，甚至可以贡献您的专业知识。如果您想学习某个主题，为什么不尝试改进文档呢！通过为 MDN 做贡献，您可以提高自己在某个技术领域的技能，并且数百万读者将从中受益。

我们很高兴地分享，在 2024 年，我们在 mdn/content GitHub 仓库中看到了以下贡献：

915 位不同的作者做出了贡献。
约 4300 个拉取请求已打开。
约 1500 个问题已打开。

我们要向 2024 年所有做出贡献的人表示衷心的感谢，并希望在 2025 年继续见到您。我们期待看到的首批重大变化之一是 JavaScript Temporal 即将到来，其支持计划在 Firefox 135 中上线。Josh-Cena 撰写了一个巨大的 Temporal 拉取请求，这意味着您很快就可以在 MDN 上阅读 Temporal 文档了。

希望您喜欢这篇博文！如果您有任何想法，请随时与我们联系。