# word2pdf

**Repository Path**: csdn-zeng8750_admin/word2pdf

## Basic Information

- **Project Name**: word2pdf
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# word2pdf

> 基于 **Docx4j + Apache FOP** 的 Word 转 PDF Spring Boot 服务

---

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 2.7.18 | Web 框架 |
| Docx4j | 11.4.9 | Word 文档解析（OpenXML） |
| Apache FOP | 2.9 | PDF 渲染引擎 |
| Java | 8+ | 运行环境 |

---

## 项目结构

```
word2pdf/
├── src/
│   ├── main/
│   │   ├── java/com/word2pdf/
│   │   │   ├── Word2PdfApplication.java              # 启动类
│   │   │   ├── config/
│   │   │   │   ├── Word2PdfProperties.java            # 配置属性
│   │   │   │   ├── WebMvcConfig.java                  # 根路径映射
│   │   │   │   └── CorsConfig.java                    # 跨域配置
│   │   │   ├── controller/
│   │   │   │   ├── ConvertController.java             # 转换接口
│   │   │   │   ├── FontController.java                # 字体诊断接口
│   │   │   │   └── GlobalExceptionHandler.java       # 全局异常处理
│   │   │   └── service/
│   │   │       ├── ConvertService.java                # 核心转换逻辑
│   │   │       └── FontDiagnosticService.java        # 字体诊断
│   │   └── resources/
│   │       ├── static/
│   │       │   └── index.html                        # 前端上传页面
│   │       ├── application.yml                        # 配置文件
│   │       └── fonts/                                 # 自定义字体目录
│   └── test/
│       └── java/com/word2pdf/
│           └── ConvertServiceTest.java               # 单元测试
├── pom.xml
└── README.md
```

---

## 前端页面

启动服务后，直接访问根路径即可使用可视化上传页面：

```
http://localhost:8080/
```

### 页面功能

| 功能 | 说明 |
|------|------|
| 服务状态指示 | 每 30 秒自动检测后端是否可用 |
| 拖拽上传 | 支持拖拽或点击上传 `.docx` / `.doc` 文件 |
| 前端格式校验 | 自动拦截非 Word 文件（非 .docx/.doc 提示错误） |
| 前端大小校验 | 超过 50MB 自动提示 |
| 转换进度 | 实时进度条 + 完成后自动触发 PDF 下载 |
| 错误反馈 | 转换失败时显示具体错误原因 |
| 字体诊断入口 | 提示用户检查中文字体支持 |

---

## 快速启动

### 1. 环境准备

```bash
# 确认 Java 版本（>= 8）
java -version

# 确认 Maven
mvn -version
```

### 2. 中文字体配置（重要！）

**方式一：复制系统字体（推荐 Windows）**

```bash
# 将 Windows 中文字体复制到项目字体目录
copy C:\Windows\Fonts\simsun.ttc src\main\resources\fonts\
copy C:\Windows\Fonts\simhei.ttf src\main\resources\fonts\
copy C:\Windows\Fonts\msyh.ttc   src\main\resources\fonts\
```

**方式二：Linux 服务器安装中文字体**

```bash
# Ubuntu / Debian
apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei

# CentOS / RHEL
yum install -y wqy-zenhei-fonts wqy-microhei-fonts

fc-cache -fv
```

**方式三：指定自定义字体目录（application.yml）**

```yaml
word2pdf:
  font-dir: /path/to/your/fonts
```

### 3. 编译 & 启动

```bash
mvn clean package -DskipTests
java -jar target/word2pdf-1.0.0.jar
```

或直接运行：

```bash
mvn spring-boot:run
```

---

## API 接口

### POST `/api/convert/pdf` — Word 转 PDF

| 参数 | 类型 | 说明 |
|------|------|------|
| file | MultipartFile | .doc / .docx 文件 |

**响应**：`application/pdf` 字节流，浏览器自动下载

**示例（curl）**：

```bash
curl -X POST http://localhost:8080/api/convert/pdf \
  -F "file=@your_document.docx" \
  -o output.pdf
```

**示例（HTTPie）**：

```bash
http --form POST http://localhost:8080/api/convert/pdf \
  file@your_document.docx \
  --output output.pdf
```

---

### GET `/api/convert/health` — 健康检查

```bash
curl http://localhost:8080/api/convert/health
# 返回：word2pdf service is running
```

---

### GET `/api/fonts` — 查看可用字体列表

```bash
curl http://localhost:8080/api/fonts
```

```json
{
  "totalCount": 48,
  "chineseCount": 6,
  "hasChinese": true,
  "chineseFonts": ["SimHei", "SimSun", "Microsoft YaHei", ...],
  "allFonts": [...]
}
```

---

### GET `/api/fonts/chinese` — 检查关键中文字体状态

```bash
curl http://localhost:8080/api/fonts/chinese
```

```json
{
  "SimSun": true,
  "SimHei": false,
  "Microsoft YaHei": true,
  ...
}
```

---

## 配置说明

`application.yml` 关键配置：

```yaml
server:
  port: 8080                        # 服务端口

spring:
  servlet:
    multipart:
      max-file-size: 50MB           # 单文件最大大小
      max-request-size: 50MB        # 请求最大大小

word2pdf:
  output-dir: ""                    # PDF 保存目录（留空用系统临时目录）
  font-dir: ""                      # 自定义字体目录（留空用 classpath:fonts/）
```

---

## 已知限制

| 场景 | 说明 |
|------|------|
| 复杂表格嵌套 | FOP 渲染可能出现轻微错位 |
| 艺术字 / SmartArt | 不支持，会降级为纯文本 |
| 宏 / VBA | 忽略，不执行 |
| `.doc` 格式（老版本） | 支持有限，建议转为 `.docx` 后处理 |
| 中文乱码 | 确保服务器已安装中文字体，参考上方"中文字体配置" |

---

## 排查中文乱码

1. 访问 `GET /api/fonts/chinese` 检查字体是否加载
2. 若所有字体均为 `false`，按上方步骤安装/配置字体
3. 重启服务后再次测试

---

## License

Apache 2.0