wp_get_attachment_url()

💡 云策文档标注

概述

wp_get_attachment_url() 函数用于获取附件的 URL，支持通过 wp_get_attachment_url 过滤器修改输出。注意该函数不会对 URL 进行编码，若附件文件名包含无效字符，需手动处理。

关键要点

参数 $attachment_id 可选，默认为全局 $post，返回字符串或 false
可通过 wp_get_attachment_url 过滤器自定义 URL 输出
函数不进行 URL 编码，需使用 rawurlencode() 处理文件名
提供示例代码获取根相对 URL 并编码文件名
相关函数包括 get_attachment_link、wp_insert_attachment 等

代码示例

$parsed = parse_url( wp_get_attachment_url( $attachment->ID ) );
$url = dirname( $parsed['path'] ) . '/' . rawurlencode( basename( $parsed['path'] ) );

注意事项

若需附件页面 URI 而非文件本身，使用 get_attachment_link
在 SSL 前端非管理页面自动转换为 HTTPS
内部处理基于上传目录和元数据，兼容旧版本 GUID 回退

📄 原文内容

Retrieves the URL for an attachment.

Parameters

$attachment_idintoptional: Attachment post ID. Defaults to global $post.

Return

string|false Attachment URL, otherwise false.

More Information

You can change the output of this function through the wp get attachment url filter.

This function will not URL encode the URL. If you have attachments with invalid characters in their name, you should raw URL encode the output of this function in order to have a valid URL.

Sample code that gives you a root-relative URL to your attachment:

<pre>$parsed = parse_url( wp_get_attachment_url( $attachment->ID ) );
$url = dirname( $parsed [ 'path' ] ) . '/' . rawurlencode( basename( $parsed[ 'path' ] ) );</pre>
<pre>

If you want a URI for the attachment page, not the attachment file itself, you can use get_attachment_link.

Also refer: wp_insert_attachment, wp_upload_dir, wp_get_attachment_image_src

Source

function wp_get_attachment_url( $attachment_id = 0 ) {
	global $pagenow;

	$attachment_id = (int) $attachment_id;

	$post = get_post( $attachment_id );

	if ( ! $post ) {
		return false;
	}

	if ( 'attachment' !== $post->post_type ) {
		return false;
	}

	$url = '';
	// Get attached file.
	$file = get_post_meta( $post->ID, '_wp_attached_file', true );
	if ( $file ) {
		// Get upload directory.
		$uploads = wp_get_upload_dir();
		if ( $uploads && false === $uploads['error'] ) {
			// Check that the upload base exists in the file location.
			if ( str_starts_with( $file, $uploads['basedir'] ) ) {
				// Replace file location with url location.
				$url = str_replace( $uploads['basedir'], $uploads['baseurl'], $file );
			} elseif ( str_contains( $file, 'wp-content/uploads' ) ) {
				// Get the directory name relative to the basedir (back compat for pre-2.7 uploads).
				$url = trailingslashit( $uploads['baseurl'] . '/' . _wp_get_attachment_relative_path( $file ) ) . wp_basename( $file );
			} else {
				// It's a newly-uploaded file, therefore $file is relative to the basedir.
				$url = $uploads['baseurl'] . "/$file";
			}
		}
	}

	/*
	 * If any of the above options failed, Fallback on the GUID as used pre-2.7,
	 * not recommended to rely upon this.
	 */
	if ( ! $url ) {
		$url = get_the_guid( $post->ID );
	}

	// On SSL front end, URLs should be HTTPS.
	if ( is_ssl() && ! is_admin() && 'wp-login.php' !== $pagenow ) {
		$url = set_url_scheme( $url );
	}

	/**
	 * Filters the attachment URL.
	 *
	 * @since 2.1.0
	 *
	 * @param string $url           URL for the given attachment.
	 * @param int    $attachment_id Attachment post ID.
	 */
	$url = apply_filters( 'wp_get_attachment_url', $url, $post->ID );

	if ( ! $url ) {
		return false;
	}

	return $url;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_get_attachment_url’, string $url, int $attachment_id ): Filters the attachment URL.

Uses	Description
wp_get_upload_dir()`wp-includes/functions.php`	Retrieves uploads directory information.
_wp_get_attachment_relative_path()`wp-includes/media.php`	Gets the attachment path relative to the upload directory.
is_ssl()`wp-includes/load.php`	Determines if SSL is used.
set_url_scheme()`wp-includes/link-template.php`	Sets the scheme for a URL.
get_the_guid()`wp-includes/post-template.php`	Retrieves the Post Global Unique Identifier (guid).
wp_basename()`wp-includes/formatting.php`	i18n-friendly version of basename().
trailingslashit()`wp-includes/formatting.php`	Appends a trailing slash.
is_admin()`wp-includes/load.php`	Determines whether the current request is for an administrative interface page.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_post_meta()`wp-includes/post.php`	Retrieves a post meta field for the given post ID.
get_post()`wp-includes/post.php`	Retrieves post data given a post ID or post object.

Show 6 more Show less

Used by	Description
wp_copy_parent_attachment_properties()`wp-admin/includes/image.php`	Copy parent attachment properties to newly cropped image.
get_media_states()`wp-admin/includes/template.php`	Retrieves an array of media states from an attachment.
wp_get_original_image_url()`wp-includes/post.php`	Retrieves the URL to an original attachment image.
wp_media_personal_data_exporter()`wp-includes/media.php`	Finds and exports attachments associated with an email address.
WP_Widget_Media_Audio::render_media()`wp-includes/widgets/class-wp-widget-media-audio.php`	Render the media on the frontend.
WP_Widget_Media_Video::render_media()`wp-includes/widgets/class-wp-widget-media-video.php`	Render the media on the frontend.
WP_Widget_Media_Image::render_media()`wp-includes/widgets/class-wp-widget-media-image.php`	Render the media on the frontend.
WP_Customize_Manager::import_theme_starter_content()`wp-includes/class-wp-customize-manager.php`	Imports theme starter content into the customized state.
get_header_video_url()`wp-includes/theme.php`	Retrieves header video URL for custom header.
WP_REST_Attachments_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php`	Prepares a single attachment output for response.
WP_Site_Icon::create_attachment_object()`wp-admin/includes/class-wp-site-icon.php`	Creates an attachment ‘object’.
export_wp()`wp-admin/includes/export.php`	Generates the WXR export file for download.
wp_save_image()`wp-admin/includes/image-edit.php`	Saves image to post, along with enqueued changes in `$_REQUEST['history']`.
_load_image_to_edit_path()`wp-admin/includes/image.php`	Retrieves the path or URL of an attachment’s attached file.
edit_form_image_editor()`wp-admin/includes/media.php`	Displays the image and editor in the post editor
attachment_submitbox_metadata()`wp-admin/includes/media.php`	Displays non-editable attachment metadata in the publish meta box.
get_attachment_fields_to_edit()`wp-admin/includes/media.php`	Retrieves the attachment fields to edit form fields.
media_sideload_image()`wp-admin/includes/media.php`	Downloads an image from the specified URL, saves it as an attachment, and optionally attaches it to a post.
image_link_input_fields()`wp-admin/includes/media.php`	Retrieves HTML for the Link URL buttons with the default link type as specified.
WP_Media_List_Table::_get_row_actions()`wp-admin/includes/class-wp-media-list-table.php`
Custom_Image_Header::create_attachment_object()`wp-admin/includes/class-custom-image-header.php`	Creates an attachment ‘object’.
Custom_Image_Header::ajax_header_crop()`wp-admin/includes/class-custom-image-header.php`	Gets attachment uploaded by Media Manager, crops it, then saves it as a new object. Returns JSON-encoded object details.
Custom_Image_Header::step_3()`wp-admin/includes/class-custom-image-header.php`	Displays third step of custom header image page.
_delete_attachment_theme_mod()`wp-includes/theme.php`	Checks an attachment being deleted to see if it’s a header or background image.
get_uploaded_header_images()`wp-includes/theme.php`	Gets the header images uploaded for the active theme.
get_the_attachment_link()`wp-includes/deprecated.php`	Retrieve HTML content of attachment image with link.
get_attachment_icon_src()`wp-includes/deprecated.php`	Retrieve icon URL and Path.
wp_get_attachment_link()`wp-includes/post-template.php`	Retrieves an attachment page link using an image or icon, if possible.
prepend_attachment()`wp-includes/post-template.php`	Wraps attachment in paragraph tag before content.
get_post_galleries()`wp-includes/media.php`	Retrieves galleries from the passed post’s content.
wp_prepare_attachment_for_js()`wp-includes/media.php`	Prepares an attachment post object for JS, where it is expected to be JSON-encoded and fit into an Attachment model.
wp_video_shortcode()`wp-includes/media.php`	Builds the Video shortcode output.
wp_playlist_shortcode()`wp-includes/media.php`	Builds the Playlist shortcode output.
wp_audio_shortcode()`wp-includes/media.php`	Builds the Audio shortcode output.
image_get_intermediate_size()`wp-includes/media.php`	Retrieves the image’s intermediate size (resized) path, width, and height.
image_downsize()`wp-includes/media.php`	Scales an image to fit a particular size (such as ‘thumb’ or ‘medium’).
redirect_canonical()`wp-includes/canonical.php`	Redirects incoming links to the proper URL based on the site url.
wp_xmlrpc_server::_prepare_media_item()`wp-includes/class-wp-xmlrpc-server.php`	Prepares media item data for return in an XML-RPC object.

Show 33 more Show less

Changelog

Version	Description
2.1.0	Introduced.

User Contributed Notes

Skip to note 3 content

Codex

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
Basic Example
```
 
```
Outputs something like http://example.net/wp-content/uploads/filename
Log in to add feedback

Skip to note 4 content

Codex

10 years ago

Use Post Thumbnail as Background Image

if ( have_posts() ) : while ( have_posts() ) : the_post(); 
    if ( has_post_thumbnail() ) {
        $feat_image_url = wp_get_attachment_url( get_post_thumbnail_id() );
        echo '<div style="background-image:url('.$feat_image_url.');"></div>';
    }
    endwhile;
endif;

云策 WordPress 开发者社区

函数文档