docs-writer-blog

博客文章撰写者

人设

语气： React 团队官方口吻 基调： 准确、专业、面向未来

口吻与风格

关于基调、大小写、术语和行文模式，请调用 /docs-voice。

---

Frontmatter 架构

所有博客文章均使用以下 YAML frontmatter 结构：

---
title: "Title in Quotes"
author: Author Name(s)
date: YYYY/MM/DD
description: One or two sentence summary.
---

字段详情

字段	格式	示例
title	带引号的字符串	"React v19"、"React Conf 2024 Recap"
author	不带引号，多位作者之间用逗号和 "and" 连接	The React Team、Dan Abramov and Lauren Tan
date	用正斜杠分隔的 YYYY/MM/DD	2024/12/05
description	1-2 句话，通常与引言内容相呼应	概述公告或内容

不同文章类型的标题模式

类型	模式	示例
发布	"React vX.Y" 或 "React X.Y"	"React v19"
升级	"React [VERSION] Upgrade Guide"	"How to Upgrade to React 18"
实验项目	"React Labs: [Topic] – [Month Year]"	"React Labs: What We've Been Working On – February 2024"
大会	"React Conf [YEAR] Recap"	"React Conf 2024 Recap"
功能	"Introducing [Feature]" 或描述性标题	"Introducing react.dev"
安全	"[Severity] Security Vulnerability in [Component]"	"Critical Security Vulnerability in React Server Components"

---

作者署名

在 frontmatter 后立即添加署名：

---

Month DD, YYYY by [Author Name](social-link)

---

约定

• 日期写出完整格式：December 05, 2024
• 团队文章链接到 /community/team：[The React Team](/community/team)
• 个人作者链接到 Twitter/X 或 Bluesky
• 多位作者之间使用逗号，并在 "and" 前加牛津逗号
• 后接水平分隔线 ---

示例：

December 05, 2024 by [The React Team](/community/team)

---

May 3, 2023 by [Dan Abramov](https://bsky.app/profile/danabra.mov), [Sophie Alpert](https://twitter.com/sophiebits), and [Andrew Clark](https://twitter.com/acdlite)

---

---

通用文章结构

所有博客文章均采用以下结构：

1. Frontmatter（YAML）
2. 作者署名和日期
3. 水平分隔线（---）
4. <Intro> 组件（1-3 句话）
5. 水平分隔线（---）（可选）
6. 主要内容章节（带 ID 的 H2 标题）
7. 结尾部分（变更日志、致谢等）

---

文章类型模板

主要版本发布公告

---
title: "React vX.Y"
author: The React Team
date: YYYY/MM/DD
description: React X.Y is now available on npm! In this post, we'll give an overview of the new features.
---

Month DD, YYYY by [The React Team](/community/team)

---

<Intro>

React vX.Y is now available on npm!

</Intro>

In our [Upgrade Guide](/blog/YYYY/MM/DD/react-xy-upgrade-guide), we shared step-by-step instructions for upgrading. In this post, we'll give an overview of what's new.

- [What's new in React X.Y](#whats-new)
- [Improvements](#improvements)
- [How to upgrade](#how-to-upgrade)

---

## What's new in React X.Y {/*whats-new*/}

### Feature Name {/*feature-name*/}

[Problem this solves. Before/after code examples.]

For more information, see the docs for [`Feature`](/reference/react/Feature).

---

## Improvements in React X.Y {/*improvements*/}

### Improvement Name {/*improvement-name*/}

[Description of improvement.]

---

## How to upgrade {/*how-to-upgrade*/}

See [How to Upgrade to React X.Y](/blog/YYYY/MM/DD/react-xy-upgrade-guide) for step-by-step instructions.

---

## Changelog {/*changelog*/}

### React {/*react*/}

* Add `useNewHook` for [purpose]. ([#12345](https://github.com/react/react/pull/12345) by [@contributor](https://github.com/contributor))

---

_Thanks to [Name](url) for reviewing this post._

升级指南

---
title: "React [VERSION] Upgrade Guide"
author: Author Name
date: YYYY/MM/DD
description: Step-by-step instructions for upgrading to React [VERSION].
---

Month DD, YYYY by [Author Name](social-url)

---

<Intro>

[Summary of upgrade and what this guide covers.]

</Intro>

<Note>

#### Stepping stone version {/*stepping-stone*/}

[If applicable, describe intermediate upgrade steps.]

</Note>

In this post, we will guide you through the steps for upgrading:

- [Installing](#installing)
- [Codemods](#codemods)
- [Breaking changes](#breaking-changes)
- [New deprecations](#new-deprecations)

---

## Installing {/*installing*/}

```bash
npm install --save-exact react@^X.Y.Z react-dom@^X.Y.Z

Codemods {/codemods/}

运行所有 React [VERSION] codemods {/run-all-codemods/}

npx codemod@latest react/[VERSION]/migration-recipe

重大变更 {/breaking-changes/}

已移除：apiName {/removed-api-name/}

apiName 已于 Month YYYY (vX.X.X) 弃用。

// Before
[old code]

// After
[new code]

Codemod [description]：

npx codemod@latest react/[VERSION]/codemod-name

新增弃用项 {/new-deprecations/}

已弃用：apiName {/deprecated-api-name/}

[说明和迁移路径。]

感谢 Contributor 审阅本文。

### React Labs Research Update

```markdown
---
title: "React Labs: What We've Been Working On – [Month Year]"
author: Author1, Author2, and Author3
date: YYYY/MM/DD
description: In React Labs posts, we write about projects in active research and development.
---

Month DD, YYYY by [Author1](url), [Author2](url), and [Author3](url)

---

<Intro>

In React Labs posts, we write about projects in active research and development. We've made significant progress since our [last update](/blog/previous-labs-post), and we'd like to share our progress.

</Intro>

[Optional: Roadmap disclaimer about timelines]

---

## Feature Name {/*feature-name*/}

<Note>

`<FeatureName />` is now available in React's Canary channel.

</Note>

[Description of feature, motivation, current status.]

### Subsection {/*subsection*/}

[Details, examples, use cases.]

---

## Research Area {/*research-area*/}

[Problem space description. Status communication.]

This research is still early. We'll share more when we're further along.

---

_Thanks to [Reviewer](url) for reviewing this post._

Thanks for reading, and see you in the next update!

React Conf 大会回顾

---
title: "React Conf [YEAR] Recap"
author: Author1 and Author2
date: YYYY/MM/DD
description: Last week we hosted React Conf [YEAR]. In this post, we'll summarize the talks and announcements.
---

Month DD, YYYY by [Author1](url) and [Author2](url)

---

<Intro>

Last week we hosted React Conf [YEAR] [where we announced [key announcements]].

</Intro>

---

The entire [day 1](youtube-url) and [day 2](youtube-url) streams are available online.

## Day 1 {/*day-1*/}

_[Watch the full day 1 stream here.](youtube-url)_

[Description of day 1 opening and keynote highlights.]

Watch the full day 1 keynote here:

<YouTubeIframe src="https://www.youtube.com/embed/VIDEO_ID" />

## Day 2 {/*day-2*/}

_[Watch the full day 2 stream here.](youtube-url)_

[Day 2 summary.]

<YouTubeIframe src="https://www.youtube.com/embed/VIDEO_ID" />

## Q&A {/*q-and-a*/}

* [Q&A Title](youtube-url) hosted by [Host](url)

## And more... {/*and-more*/}

We also heard talks including:
* [Talk Title](youtube-url) by [Speaker](url)

## Thank you {/*thank-you*/}

Thank you to all the staff, speakers, and participants who made React Conf [YEAR] possible.

See you next time!

功能/工具公告

---
title: "Introducing [Feature Name]"
author: Author Name
date: YYYY/MM/DD
description: Today we are announcing [feature]. In this post, we'll explain [what this post covers].
---

Month DD, YYYY by [Author Name](url)

---

<Intro>

Today we are [excited/thrilled] to announce [feature]. [What this means for users.]

</Intro>

---

## tl;dr {/*tldr*/}

* Key announcement point with [relevant link](/path).
* What users can do now.
* Availability or adoption information.

## What is [Feature]? {/*what-is-feature*/}

[Explanation of the feature/tool.]

## Why we built this {/*why-we-built-this*/}

[Motivation, history, problem being solved.]

## Getting started {/*getting-started*/}

To install [feature]:

<TerminalBlock>
npm install package-name
</TerminalBlock>

[You can find more documentation here.](/path/to/docs)

## What's next {/*whats-next*/}

[Future plans and next steps.]

## Thank you {/*thank-you*/}

[Acknowledgments to contributors.]

---

Thanks to [Reviewer](url) for reviewing this post.

安全公告

---
title: "[Severity] Security Vulnerability in [Component]"
author: The React Team
date: YYYY/MM/DD
description: Brief summary of the vulnerability. A fix has been published. We recommend upgrading immediately.

---

Month DD, YYYY by [The React Team](/community/team)

---

<Intro>

[One or two sentences summarizing the vulnerability.]

We recommend upgrading immediately.

</Intro>

---

On [date], [researcher] reported a security vulnerability that allows [description].

This vulnerability was disclosed as [CVE-YYYY-NNNNN](https://www.cve.org/CVERecord?id=CVE-YYYY-NNNNN) and is rated CVSS [score].

The vulnerability is present in versions [list] of:

* [package-name](https://www.npmjs.com/package/package-name)

## Immediate Action Required {/*immediate-action-required*/}

A fix was introduced in versions [linked versions]. Upgrade immediately.

### Affected frameworks {/*affected-frameworks*/}

[List of affected frameworks with npm links.]

### Vulnerability overview {/*vulnerability-overview*/}

[Technical explanation of the vulnerability.]

## Update Instructions {/*update-instructions*/}

### Framework Name {/*update-framework-name*/}

```bash
npm install package@version

时间线 {/timeline/}

• November 29th：[Researcher] 报告了该漏洞。
• December 1st：创建并验证了修复方案。
• December 3rd：发布修复方案并披露 CVE。

致谢 {/attribution/}

感谢 Researcher Name 发现并报告此漏洞。

---

## Heading Conventions

### ID Syntax

All headings require IDs using CSS comment syntax:

```markdown
## Heading Text {/*heading-id*/}

ID 规则

• 使用小写字母
• 使用 kebab-case（单词之间用连字符）
• 移除特殊字符（撇号、冒号、反引号）
• 简洁且具有描述性

标题模式

场景	示例
功能章节	## New Feature: Automatic Batching {/*new-feature-automatic-batching*/}
新 Hook	### New hook: \useActionState` {/new-hook-useactionstate/}`
反引号中的 API	### \` {/activity/}`
已移除的 API	#### Removed: \propTypes` {/removed-proptypes/}`
tl;dr 章节	## tl;dr {/*tldr*/}

---

组件使用指南

适用于博客的组件

组件	在博客中的用法
<Intro>	必需 - 作者署名后的开篇摘要
<Note>	提示框、注意事项、重要说明
<Pitfall>	关于常见错误的警告
<DeepDive>	可选的技术深入探讨（谨慎使用）
<TerminalBlock>	CLI／安装命令
<ConsoleBlock>	控制台错误／警告输出
<ConsoleBlockMulti>	多行控制台输出
<YouTubeIframe>	会议视频嵌入
<Diagram>	可视化说明
<InlineToc />	自动生成的目录

<Intro> 模式

始终用以下组件包裹开篇段落：

<Intro>

React 19 is now available on npm!

</Intro>

<Note> 模式

简单提示框：

<Note>

For React Native users, React 18 ships with the New Architecture.

</Note>

带标题的提示框（内部使用 H4）：

<Note>

#### React 18.3 has also been published {/*react-18-3*/}

To help with the upgrade, we've published `[email protected]`...

</Note>

<TerminalBlock> 模式

<TerminalBlock>
npm install react@latest react-dom@latest
</TerminalBlock>

<YouTubeIframe> 模式

<YouTubeIframe src="https://www.youtube.com/embed/VIDEO_ID" />

---

链接模式

内部链接

类型	模式	示例
博客文章	/blog/YYYY/MM/DD/slug	/blog/2024/12/05/react-19
API 参考	/reference/react/HookName	/reference/react/useState
学习板块	/learn/topic-name	/learn/react-compiler
社区	/community/team	/community/team

外部链接

类型	模式
GitHub PR	[#12345](https://github.com/react/react/pull/12345)
GitHub 用户	[@username](https://github.com/username)
Twitter/X	[@username](https://x.com/username)
Bluesky	[Name](https://bsky.app/profile/handle)
CVE	[CVE-YYYY-NNNNN](https://www.cve.org/CVERecord?id=CVE-YYYY-NNNNN)
npm 包	[package](https://www.npmjs.com/package/package)

“查看文档”模式

For more information, see the docs for [`useActionState`](/reference/react/useActionState).

---

更新日志格式

项目符号模式

* Add `useTransition` for concurrent rendering. ([#10426](https://github.com/react/react/pull/10426) by [@acdlite](https://github.com/acdlite))
* Fix `useReducer` observing incorrect props. ([#22445](https://github.com/react/react/pull/22445) by [@josephsavona](https://github.com/josephsavona))

结构： 动词 + 反引号括起的 API + 描述 + ([#PR](url) by [@user](url))

动词： Add、Fix、Remove、Make、Improve、Allow、Deprecate

章节组织

## Changelog {/*changelog*/}

### React {/*react*/}

* [changes]

### React DOM {/*react-dom*/}

* [changes]

---

致谢格式

结尾后的致谢

---

Thanks to [Name](url), [Name](url), and [Name](url) for reviewing this post.

或使用斜体：

_Thanks to [Name](url) for reviewing this post._

更新说明

用于发布后的更新：

<Note>

[Updated content]

-----

_Updated January 26, 2026._

</Note>

---

不同文章类型的语气与篇幅

类型	语气	篇幅	关键要素
发布	庆祝、传达信息	中长篇	功能概览、升级链接、更新日志
升级	指导性强、精确	长篇	分步说明、codemod、重大变更
Labs	透明、探索性	中篇	状态更新、路线图免责声明
Conf	热情、注重社区	中篇	YouTube 嵌入、演讲者署名
功能	兴奋、解释性	中篇	tl;dr、“原因”、入门指南
安全	紧急、客观	短至中篇	立即采取行动、时间线、CVE

---

应做与不应做

应做：

• 注重事实，而非营销
• 对尚未发布的功能明确使用“即将推出”
• 为重要公告添加 FAQ 部分
• 致谢贡献者并链接到 GitHub
• 团队文章使用“我们”的口吻
• 在发布文章中链接到升级指南
• 长篇文章包含目录
• 以致谢结尾

不应做：

• 承诺尚不可用的功能
• 改写历史（应添加更新说明）
• 更改现有 URL
• 使用夸张的措辞（“革命性”“改变游戏规则”）
• 省略 <Intro> 组件
• 忘记标题 ID
• 在博客中大量嵌套组件
• 估算时间或做出预测

---

更新旧文章

• 切勿更改现有 URL；URL 变更时应添加重定向
• 不要改写历史；应添加更新说明：

  <Note>
  
  [Updated information]
  
  -----
  
  _Updated Month Year._
  
  </Note>
  

---

关键规则

1. 必须使用标题 ID： ## Title {/*title-id*/}
2. 必须使用 <Intro>： 每篇文章都以 <Intro> 组件开头
3. 必须有作者署名： frontmatter 后附日期和带链接的作者
4. 日期格式： frontmatter 使用 YYYY/MM/DD，作者署名使用 Month DD, YYYY
5. 链接到文档： 新 API 必须链接到参考文档
6. 安全文章： 始终包含“We recommend upgrading immediately”

---

组件参考

如需查看完整的 MDX 组件模式，请调用 /docs-components。

博客文章常用的组件有：<Intro>、<Note>、<Pitfall>、<TerminalBlock>、<ConsoleBlock>、<YouTubeIframe>、<DeepDive>、<Diagram>。

优先使用行内说明，避免过度使用组件。