高级管理文档

💡 云策文档标注

概述

oEmbed 是 WordPress 中用于简化内容嵌入的协议,允许从外部站点(如 YouTube)获取嵌入 HTML,避免手动复制粘贴。它支持视频、图像等多种内容类型,但默认仅允许白名单中的 URL 嵌入以确保安全。

关键要点

  • oEmbed 协议用于从提供者获取嵌入内容所需的 HTML,提升嵌入便捷性。
  • WordPress 核心维护一个内部白名单,默认仅允许特定 URL 嵌入,以增强安全性。
  • 可通过 wp_oembed_add_provider() 添加支持 oEmbed 的站点到白名单。
  • 对于不支持 oEmbed 的站点,需使用 wp_embed_register_handler() 注册处理程序并提供回调函数生成 HTML。
  • 可使用 wp_oembed_remove_provider() 移除已支持的 oEmbed 提供者。
  • WordPress 4.4 起支持 oEmbed 发现,但对非白名单站点的内容类型有严格限制,如仅允许链接、引用和 iframe,并应用沙盒和安全过滤。
  • 管理员和编辑等 unfiltered_html 用户可被授予权限,以嵌入具有 oEmbed 发现标签的站点内容,但需注意安全风险。

注意事项

oEmbed 发现功能对“链接”和“照片”类型的内容过滤较轻,但仍会进行适当转义以防止恶意内容显示。开发者应谨慎处理安全设置,避免潜在漏洞。


📄 原文内容

The easy embedding feature is mostly powered by oEmbed, a protocol for consumers (such as your blog) to ask providers (such as YouTube) for the HTML needed to embed content from the provider.

oEmbed is designed to avoid the need to copy and paste HTML from the site hosting the media you wish to embed. It supports different kind of content like videos, images, text, and more.

Does This Work With Any URL?

No, not by default. The WordPress Core has an internal whitelist that will only allow certain URLs to be embeddable for security reasons. The good news is that the whitelist can be modified, and new sites and URLs can be added by registering their handle.

How Can I Add or Change Support For Websites?

Adding support for an additional website depends on whether the site supports oEmbed. oEmbed.com provides a list of hundreds of supported provides.

Adding Support For An oEmbed-Enabled Site

If a site supports oEmbed, you’ll want to call wp_oembed_add_provider() to add the site and URL format to the internal whitelist.

Adding Support For A Non-oEmbed Site

You’ll need to register a handler using wp_embed_register_handler() and provide a callback function that generates the HTML.

Removing Support for An oEmbed-Enabled Site

If you wish to remove an oEmbed-enabled provider, you’ll want to call wp_oembed_remove_provider.

What About oEmbed Discovery?

As of version 4.4, WordPress supports oEmbed discovery, but has severe limitations on what type of content can be embedded via non-whitelisted sites.

Specifically, the HTML and Video content is filtered to only allow links, blockquotes, and iframes, and these are additionally filtered to prevent insertion of malicious content. The HTML is then modified to be sandboxed and to have additional security restrictions placed on them as well.

However, if you feel you are knowledgeable enough to not require this level of safety, you can give unfiltered_html users (Administrators and Editors) the ability to embed from websites that have oEmbed discovery tags in their <head>.

The oEmbed discovery content for “link” and “photo” types is not quite so heavily filtered in this manner; however, it is properly escaped for security and to prevent any malicious content from being displayed on the site