使用react-pdf/renderer渲染PDF时出现「页面无响应」问题求助

环境版本 #

"@react-pdf/renderer": "^3.1.12",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-scripts": "5.0.1",
"web-vitals": "^2.1.4"

问题详情 #

传入DownloadFile组件的所有props均确认正确，但PDF渲染不稳定，有时能正常加载，有时会导致页面冻结。该问题可在react-pdf官方playground复现。

组件使用方式：

<PDFViewer>
   <DownloadFile
      profileImg={profileImg}
   />
</PDFViewer>

DownloadFile组件代码：

import React from 'react';
import { Page, Text, View, Document, StyleSheet, Image } from '@react-pdf/renderer';

const styles = StyleSheet.create({

    coverPage: {
        backgroundColor: "#AFEBEB",
    },
    coverPageInner: {
        margin: '50px 48px 50px 0',
        backgroundColor: "#FFFFFF",
    },
    coverPageHeader: {
        margin: '72px 63px 0 0',
        height: '64px',
        backgroundColor: '#4BA5A1',
        padding: '10px 43px 10px 139px',
        display: 'flex',
        flexDirection: 'row',
        alignItems: 'center',
    },
    coverPageHeaderLogo: {
        backgroundColor: "#FFFFFF",
        padding: '5px 9px',
        borderRadius: '50%',
        height: '44px',
        width: '44px',
        objectFit: 'contain'
    },
    coverPageHeaderText: {
        color: "#ffffff",
        fontSize: '24px',
        lineHeight: '40px',
        fontWeight: '800',
        margin: '0 0 0 10px'
    },
    coverPageMiddle: {
        margin: '75px -22px 75px 116px',
        backgroundColor: '#4BA5A1'
    },
    coverPageMiddleText: {
        fontSize: '48px',
        fontWeight: 'extrabold',
        lineHeight: '50px',
        color: '#FFFFFF'
    },
});

// Create Document Component
function DownloadFile({ profileImg }) {

    return (
        <Document>
            <Page size={"A4"} style={styles.cover__page}>
                <View style={styles.cover__page__inner}>
                    <View style={styles.cover__page__header}>
                        <Image style={styles.cover__page__header__logo} src={profileImg} alt='' />
                        <Text style={styles.cover__page__header__text}>Vardhaman Textiles</Text>
                    </View>
                    <View style={styles.cover__page__middle}>
                        <Text style={styles.cover__page__middle__text}>GHG Emission Report</Text>
                    </View>
                    <View style={styles.cover__page__lower}>
                        <Text>Powered by</Text>
                        <Image src="/assets/images/sideBarLogo.svg" alt="GreenStitch" />
                    </View>
                </View>
            </Page>
        </Document>
    )
};

export default DownloadFile

排查与解决方案 #

1. 修复样式名称不匹配问题 #

代码中存在样式对象键名和组件引用名称不匹配的问题：

• 定义的样式键是coverPage，但组件中用了styles.cover__page
• 同理coverPageInner对应cover__page__inner、coverPageHeader对应cover__page__header等，所有样式名的命名规则不一致

这种不匹配会导致渲染时样式解析异常，大概率是引发页面冻结的核心原因。将组件中的样式引用统一改为和定义一致的命名，同时补充缺失的coverPageLower样式：

// 组件内修改样式引用
<Page size={"A4"} style={styles.coverPage}>
    <View style={styles.coverPageInner}>
        <View style={styles.coverPageHeader}>
            <Image style={styles.coverPageHeaderLogo} src={profileImg} alt='' />
            <Text style={styles.coverPageHeaderText}>Vardhaman Textiles</Text>
        </View>
        <View style={styles.coverPageMiddle}>
            <Text style={styles.coverPageMiddleText}>GHG Emission Report</Text>
        </View>
        <View style={styles.coverPageLower}>
            <Text>Powered by</Text>
            <Image src="/assets/images/sideBarLogo.svg" alt="GreenStitch" />
        </View>
    </View>
</Page>

// styles中补充coverPageLower
const styles = StyleSheet.create({
    // ... 其他样式
    coverPageLower: {
        margin: 'auto 0 20px 0',
        padding: '0 43px'
    }
});

2. 优化图片加载逻辑 #

• 确保profileImg为base64格式或稳定的本地/网络资源路径，避免传入未加载完成的图片资源
• 本地图片可转换为base64嵌入代码，减少渲染时的异步加载开销

3. 升级依赖版本 #

当前使用的@react-pdf/renderer@3.1.12存在已知的渲染性能与稳定性问题，建议升级到最新稳定版，新版本修复了不少页面冻结、内存泄漏类bug。

替代库推荐 #

如果问题仍未解决，可尝试以下PDF生成库：

• jsPDF + html2canvas：适合直接将现有HTML组件转换为PDF，学习成本低，兼容性强
• @react-pdf/renderer v4.x：官方重构版本，全新渲染引擎，性能与稳定性大幅提升
• pdfmake：基于JavaScript的声明式PDF生成库，适合复杂文档定制

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