Payload CMS内部链接渲染异常求助：Lexical转HTML失败

问题原因 #

默认的LinkHTMLConverter无法解析Payload内部链接的文档引用，只会生成占位符#作为href值。要修复这个问题，需要自定义转换器来读取内部链接关联的文档数据并生成正确的URL。

解决方案 #

自定义链接转换器，识别内部链接类型并从关联文档中提取URL（比如slug字段）：

import type { Block } from 'payload'
import type { LexicalNode } from 'lexical'

import {
  FixedToolbarFeature,
  HeadingFeature,
  InlineToolbarFeature,
  lexicalEditor,
  lexicalHTMLField
} from '@payloadcms/richtext-lexical'

import { LinkHTMLConverter } from '@payloadcms/richtext-lexical/html'

// 自定义内部链接转换器
const CustomLinkConverter = LinkHTMLConverter.extend({
  convertToHTML(node: LexicalNode) {
    const linkNode = node as any
    const { link } = linkNode

    // 处理内部链接
    if (link.type === 'internal' && link?.relationTo && link?.value) {
      // 替换为你关联文档中用于生成URL的字段（如slug、customUrl等）
      const documentSlug = link.value.slug
      // 根据Next.js前端路由结构生成完整URL
      const href = `/${documentSlug}`
      return `<a href="${href}">${this.childrenToHTML(node)}</a>`
    }

    // 处理外部链接（保留默认逻辑）
    if (link.type === 'external') {
      return `<a href="${link.url}" target="_blank" rel="noopener noreferrer">${this.childrenToHTML(node)}</a>`
    }

    // 回退到默认处理逻辑
    return super.convertToHTML(node)
  }
})

export const Content: Block = {
  slug: 'content',
  interfaceName: 'ContentBlock',
  fields: [
    {
      name: 'richText',
      type: 'richText',
      localized: true,
      editor: lexicalEditor({
        features: ({ rootFeatures }) => {
          return [
            ...rootFeatures,
            HeadingFeature({ enabledHeadingSizes: ['h2', 'h3', 'h4'] }),
            FixedToolbarFeature(),
            InlineToolbarFeature(),
          ]
        },
      }),
      label: false,
    },
    lexicalHTMLField({
      htmlFieldName: 'richText_html',
      lexicalFieldName: 'richText',
      converters: ({ defaultConverters }) => ({
        ...defaultConverters,
        // 替换默认的链接转换器
        link: CustomLinkConverter,
      }),
    }),
  ],
}

关键注意事项 #

• 确保关联的文档集合（如pages、posts）包含可用于生成URL的字段（如slug），且Payload在处理时能自动获取该字段数据（可在关系字段配置中设置populate: true）。
• 根据你的Next.js路由结构调整href生成逻辑，比如本地化路由需添加locale前缀。
• 若使用自定义URL字段或Payload的URL插件，直接替换link.value.slug为对应字段名即可。

内容的提问来源于stack exchange，提问作者14pixels