Pygame字体模块报NotImplementedError，求解决方法

我是一名C#开发者，刚接触Pygame，跟着入门教程学习时在字体功能上卡壳了——每次运行代码都会抛出NotImplementedError(missing_msg)错误，搞不清问题出在哪。

我的代码如下：

import pygame
from sys import exit

pygame.init()  # really important, cant run pygame without it!
screen = pygame.display.set_mode((800, 400))
pygame.display.set_caption('Runner')
clock = pygame.time.Clock()
test_font = pygame.font.Font(None, 50)


sky_surface = pygame.image.load('graphics/sky.png')
ground_surface = pygame.image.load('graphics/ground.png')
text_surface = test_font.render('MyGame', False, 'Green' )

while True:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            exit()
    screen.blit(sky_surface, (0, 0))
    screen.blit(ground_surface, (0, 200))
    screen.blit(text_surface, (300, 40))

    # draw all our elements and update everything
    pygame.display.update()  # updates the display surface
    clock.tick(60) # should not run faster then 60fps- set a max frame rate

错误发生在test_font = pygame.font.Font(None, 50)这一行，完整错误信息：

RuntimeWarning: use font: dlopen(/Users/hanamahmoud/PycharmProjects/pythonProject/venv/lib/python3.11/site-packages/pygame/font.cpython-311-darwin.so, 2): Library not loaded: @loader_path/libfreetype.6.dylib
  Referenced from: /Users/hanamahmoud/PycharmProjects/pythonProject/venv/lib/python3.11/site-packages/pygame/.dylibs/libfreetype.6.dylib
  Reason: image not found
(ImportError: dlopen(/Users/hanamahmoud/PycharmProjects/pythonProject/venv/lib/python3.11/site-packages/pygame/font.cpython-311-darwin.so, 2): Library not loaded: @loader_path/libfreetype.6.dylib
  Referenced from: /Users/hanamahmoud/PycharmProjects/pythonProject/venv/lib/python3.11/site-packages/pygame/.dylibs/libfreetype.6.dylib
  Reason: image not found)
  test_font = pygame.font.Font(None, 50)
Traceback (most recent call last):
  File "/Users/hanamahmoud/PycharmProjects/pythonProject/main.py", line 8, in <module>
    test_font = pygame.font.Font(None, 50)
                ^^^^^^^^^^^^^^^^
  File "/Users/hanamahmoud/PycharmProjects/pythonProject/venv/lib/python3.11/site-packages/pygame/__init__.py", line 70, in __getattr__
    raise NotImplementedError(missing_msg)
NotImplementedError: font module not available (ImportError: dlopen(/Users/hanamahmoud/PycharmProjects/pythonProject/venv/lib/python3.11/site-packages/pygame/font.cpython-311-darwin.so, 2): Library not loaded: @loader_path/libfreetype.6.dylib
  Referenced from: /Users/hanamahmoud/PycharmProjects/pythonProject/venv/lib/python3.11/site-packages/pygame/.dylibs/libfreetype.6.dylib
  Reason: image not found)

问题根源 #

这是macOS环境下Pygame依赖的libfreetype.6.dylib库加载失败导致的，属于依赖库路径错误或者安装不完整的问题。

解决步骤 #

• 重新安装Pygame（优先推荐）
  先卸载现有版本：

  pip uninstall pygame
  

  再用无缓存的方式重新安装，确保依赖完整：

  pip install pygame --upgrade --no-cache-dir
  

  如果用conda环境，换成：

  conda uninstall pygame
  conda install -c conda-forge pygame
  

• 手动修复库路径（进阶方案）
  如果重新安装没用，可以手动修正库的引用路径：

  1. 找到你的pygame .dylibs目录，比如示例中的/Users/hanamahmoud/PycharmProjects/pythonProject/venv/lib/python3.11/site-packages/pygame/.dylibs/
  2. 进入该目录执行命令：

     install_name_tool -change @loader_path/libfreetype.6.dylib @executable_path/../lib/python3.11/site-packages/pygame/.dylibs/libfreetype.6.dylib libfreetype.6.dylib
     

  注意替换成你自己的虚拟环境路径。

• 临时替代方案
  直接指定系统中存在的字体文件路径，不用默认字体：

  # macOS系统字体示例，路径按需调整
  test_font = pygame.font.Font('/Library/Fonts/Arial.ttf', 50)
  

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