在当今的技术文档工作流中，Markdown 因其简洁的语法和版本控制友好的特性，已成为开发者和技术写作者的首选格式。然而，在企业环境中，Word 文档仍然是正式报告、客户交付物和标准化文档的主流格式。

本文将分享如何使用 Free Spire.Doc for Python—一款免费的 Python 文档处理库，快速实现 Markdown 到 Word 的转换，涵盖基础转换、批量处理等实用场景，新手也能轻松上手。

一、环境准备

Free Spire.Doc for Python 是免费 Python 文档处理库，无需依赖 Microsoft Word，支持 Word 文档的创建、编辑、转换等操作，其中内置的 Markdown 解析能力，能高效实现 Markdown 到 Doc/Docx 格式的转换，且兼容常见的 Markdown 语法（标题、列表、图片、链接等）。

安装：
打开终端/命令提示符，执行以下pip安装命令：

pip install Spire.Doc.Free

二、基础实现：单篇 Markdown 转 Word

场景1：将 Markdown 文本直接转换为 Word

适用于 Markdown 内容较短、无需读取文件的场景，核心代码如下：

from spire.doc import *from spire.doc.common import *# 1. 定义要转换的Markdown文本（涵盖常见语法）markdown_text = """# 一级标题：Markdown转Word测试
## 二级标题：功能演示
### 三级标题：基础语法支持
#### 1. 段落与强调
这是一段普通段落，支持**粗体**、*斜体*、`行内代码`，以及[超链接](https://www.google.com/)。
#### 2. 列表
- 无序列表项1
- 无序列表项2
  - 子列表项
1. 有序列表项1
2. 有序列表项2
#### 3. 代码块
```python
print("Hello, Markdown to Word!")
a = 1 + 2
```"""# 1. 将markdown文本写入md文档markdown_path = "input.md"with open(markdown_path, 'w', encoding='utf-8') as f:
    f.write(markdown_text)# 2. 创建Document对象doc = Document()# 3. 加载md文档doc.LoadFromFile(markdown_path, FileFormat.Markdown)# 4. 保存为Word文档（支持.doc和.docx格式）output_path = "Markdown转Word.docx"doc.SaveToFile(output_path, FileFormat.Docx)# 5. 释放资源doc.Close()print(f"转换完成！Word文档已保存至：{output_path}")

场景2：读取 Markdown 文件转换为 Word

适用于已有.md文件的场景（如 test.md），代码更简洁：

from spire.doc import Documentfrom spire.doc import FileFormat# 1. 创建Document对象doc = Document()# 2. 直接加载Markdown文件（指定文件路径）markdown_file_path = "test.md"doc.LoadFromFile(markdown_file_path, FileFormat.Markdown)# 3. 保存为Word文档output_path = "Markdown转Word.docx"doc.SaveToFile(output_path, FileFormat.Docx)# 4. 释放资源doc.Close()print(f"文件转换完成！路径：{output_path}")

代码关键说明：

Document()：创建一个空的 Word 文档对象，是所有操作的核心载体；
LoadFromFile()：加载 Markdown 文件，第二个参数 FileFormat.Markdown 指定解析格式；
SaveToFile()：接收输出路径和文件格式（ FileFormat.Docx/ FileFormat.Doc），完成保存；
Close()：释放文档资源，避免内存占用。

三、批量转换多个 Markdown 文件

Free Spire.Doc for Python 支持批量转换一个文件夹中的多个 Markdown 文档。

import osfrom spire.doc import Documentfrom spire.doc import FileFormat# 1. 定义Markdown文件所在文件夹和输出文件夹md_folder = "./markdown_files"output_folder = "./word_files"# 2. 创建输出文件夹（若不存在）if not os.path.exists(output_folder):
    os.makedirs(output_folder)# 3. 遍历文件夹中的所有.md文件for filename in os.listdir(md_folder):    if filename.endswith(".md"):        # 拼接文件路径
        md_path = os.path.join(md_folder, filename)        # 生成输出Word文件名（替换后缀为.docx）
        output_filename = os.path.splitext(filename)[0] + ".docx"
        output_path = os.path.join(output_folder, output_filename)        # 4. 转换逻辑
        doc = Document()
        doc.LoadFromFile(md_path, FileFormat.Markdown)
        doc.SaveToFile(output_path, FileFormat.Docx)
        doc.Close()        print(f"已转换：{filename} -> {output_filename}")print("所有Markdown文件批量转换完成！")

常见问题与注意事项

格式兼容问题：部分小众 Markdown 语法（如 Mermaid 流程图、LaTeX 公式）暂不支持，转换后可能显示异常，建议提前简化这类内容；
编码问题：若 Markdown 文件含中文，建议保存为 UTF-8 编码，避免转换后出现乱码；
免费版限制：Free Spire.Doc for Python 免费版对文档页数有限制，满足日常轻量使用。

packaging - 处理Python包和版本信息

一、什么是packaging？

packaging 是一个用于处理 Python 包、版本和各种依赖规范的 Python 库。

它可以帮助你：

解析、比较和操作各种 PEP 440 兼容的版本字符串。

处理环境标记（PEP 508）。

解析和标准化依赖规范（PEP 503）。

二、应用场景

packaging 广泛应用于以下实际场景：

场景1: 工具开发者需要解析用户输入的 Python 包版本，以确保兼容性。

场景2: 构建系统需要比较不同库的版本，以决定是否进行升级或安装。

场景3: 自动化脚本需要根据当前的 Python 环境，解析和应用特定的依赖条件。

三、如何安装

使用 pip 安装

pip install packaging

# 如果安装慢的话，推荐使用国内镜像源

pip install packaging -i https://www.python64.cn/pypi/simple/

使用 PythonRun 在线运行代码（无需本地安装）

四、示例代码

packaging 库可以让你轻松地比较两个版本字符串，判断它们的大小关系。

from packaging.version import Version

# 定义两个版本字符串

version_str_1 = "2.1.0"

version_str_2 = "2.0.5"

# 将版本字符串转换为 Version 对象

version_1 = Version(version_str_1)

version_2 = Version(version_str_2)

# 比较两个版本

if version_1 > version_2:

print(f"{version_str_1} is newer than {version_str_2}")

elif version_1 < version_2:

print(f"{version_str_1} is older than {version_str_2}")

else:

print(f"{version_str_1} is the same as {version_str_2}")

# 另一个示例：比较一个开发版本和一个发布版本

dev_version_str = "1.0.0.dev1"

release_version_str = "1.0.0"

dev_version = Version(dev_version_str)

release_version = Version(release_version_str)

# 按照 PEP 440 规范，开发版本通常被认为比对应的发行版本要旧

if dev_version < release_version:

print(f"{dev_version_str} is older than {release_version_str} (as expected for dev builds)")

else:

print(f"{dev_version_str} is not older than {release_version_str}")

首先是日志，配置日志的方式也很简单

static_resources:
  listeners:
    - name: ingress_listener
      address:
        socket_address:
          address: 0.0.0.0
          port_value: 10000
      filter_chains:
        - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                stat_prefix: ingress_http
                ...
                access_log:lq2026.cn
                - name:spacexzhibo.com envoy.access_loggers.stdout
                  typed_config:                    "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
                    log_format:
                      text_format: "[%START_TIME%] \"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%\" %RESPONSE_CODE% %BYTES_SENT% %DURATION% %REQ(X-REQUEST-ID)% \"%REQ(USER-AGENT)%\" \"%REQ(X-FORWARDED-FOR)%\" %UPSTREAM_HOST% %UPSTREAM_CLUSTER% %RESPONSE_FLAGS%\n"

该配置是将日志输出在控制台，也可以直接输出为文件，然后通过工具采集走 path: /var/log/envoy/access.log
也可以直接将日志输出至kafka，并且按比例采集、只采集4xx、5xx等都可以配置，这里就不在赘述了

admin管理页面

envoy有默认的admin页面，方便查看统计信息、打开某些功能的开关等

admin:
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 9901

打开9901页面：

watermarked-envoy_ob_1

可以查看相关的统计信息、也可以打开某些开关，功能还是很丰富的

merics接入prometheus

打开了admin之后，就默认提供了相关的prometheus stats http://10.105.148.194:9901/stats/prometheus

这时只需在k8s集群外弄一个prometheus，并且采集该envoy即可

prometheus.yml

global:
  scrape_interval: 5s
  evaluation_interval:spacexzhibo.cn 5srule_files:
  - /etc/prometheus/*.rulesscrape_configs:
  - job_name: basketzhibo.cn'prometheus'
    static_configs:
    - targets: ['localhost:9090']  - job_name: "envoy"
    metrics_path: /stats/prometheus
    static_configs:
    - targets: ["10.105.148.194:9901"]

docker run -d --name prometheus \
  -p 9090:9090 \
  -v ./prometheus.yml:starlinkzhibo.com/etc/prometheus/prometheus.yml \
  -v /usr/share/zoneinfo/Asia/Shanghai:/etc/localtime \
  registry.cn-beijing.aliyuncs.com/wilsonchai/prometheus:v3.5.0

traces接入jaeger

jaeger的安装可以参考这里： opentelemetry全链路初探--埋点与jaeger

jaeger启动之后，改造一下envoy的配置，这里要特别注意，不同版本的配置不一样，我这里envoy的版本是：v1.32

static_resources:
  listeners:
    - name: ingress_listener
      filter_chains:
        - filters:
            - name:starlinkzhibo.cn envoy.filters.network.http_connection_manager
              typed_config:
                ...
                tracing:
                  provider:
                    name: envoy.tracers.opentelemetry
                    typed_config:
                      "@type": type.googleapis.com/envoy.config.trace.v3.OpenTelemetryConfig
                      service_name: envoy-proxy
                      grpc_service:
                        envoy_grpc:
                          cluster_name: jaeger_otlp_collector
                ...
  clusters:
    ...
    - name: jaeger_otlp_collector
      type: LOGICAL_DNS
      connect_timeout: 5s
      lb_policy:xzhibo.com.cn ROUND_ROBIN
      http2_protocol_options: {}      load_assignment:
        cluster_name: jaeger_otlp_collector
        endpoints:
        - lb_endpoints:
          - endpoint:
              address:
                socket_address:
                  address: 10.22.12.178
                  port_value: 4317
    ...

修改完成之后重启下envoy

jaeger成功接收到了来自envoy的trace

ITPub博客

快速实现 Markdown 到 Word 的转换，涵盖基础转换