简介：面向Python初学者与图形编程爱好者的Pygame实战案例，围绕新年烟花动画展开，帮助读者在节日氛围中理解粒子系统、动画渲染与音效播放的基本流程。压缩包共1个docx文档，约16KB，以图文讲解配合完整代码示例呈现，涵盖环境准备、Pygame初始化、窗口与颜色设置、Particle粒子类、Firework发射与爆炸逻辑，以及背景音乐加载和主循环事件处理。读者可据此运行并调整烟花颜色、粒子数量、发射频率与音乐文件路径，逐步搭建可交互的烟花展示程序，同时掌握图形界面应用中的对象封装、随机运动与生命周期管理思路。目前已有143人学习，适合作为入门练习或节日小项目参考。

1. 装 Pygame 之前先想清楚：一套烟花动画动画示例的环境清单

元旦前一周，某开发者把一份 Python + Pygame 的新年烟花动画代码发到群里，附了一句「pip install pygame就能跑」。三个人同时下载，两个人在pygame.error: video system not initialized上卡了一晚上，另一个跑起来了但屏幕全黑——背景音乐路径写错，mixer初始化失败，主循环第一帧就退出。这种图形界面小 Demo 看着简单，实际把解释器版本、SDL 显示与音频后端、素材路径三件事绑在一起，任何一处不对，表现出来都是「黑屏 + 没声音」这同一个症状。这套环境适合拿 Pygame 练粒子系统和动画循环的初学者，也适合想在新年活动里加一段烟花氛围的开发者。下面按我实际装过的顺序，从环境清单讲到跑通自查。

2. 建隔离环境：Python 3.10 配 pygame 2.5 的环境搭建方案

Pygame 这类依赖 SDL 的库，最大的不确定性不在代码，在「你的解释器有没有现成的预编译 wheel」。装环境这一步走歪，后面调代码全是白费劲。我一般把这件事拆成三步：定解释器、建虚拟环境、装库并固化版本，每一步都留一个能回退的点。

2.1 解释器版本怎么定：别追最新，追有轮子的

Pygame 2.x 在 Windows 和 macOS 上发布的是预编译 wheel，文件名带cp310、cp311这种 ABI 标签，标签对不上就只能从源码编译，而源码编译要本地 SDL2 开发头文件，那是另一场事故。所以选版本的原则很简单：选发布了一年左右、wheel 覆盖完整的版本。Python 3.10 和 3.11 是当前最稳的两档，3.12 也能用，但个别旧版 Pygame 轮子还没跟上；3.13 这种刚出的解释器，等一段时间再说，赶新没有任何收益。

先确认机器上到底装了哪几个解释器，别凭记忆：

# Windows：列出所有已安装的 Python py -0p # macOS / Linux：看默认解释器和版本 python3 --version which -a python3

py -0p会打出每个已安装版本对应的可执行文件路径，比在开始菜单里翻要靠谱。macOS 上如果which -a python3出来好几条，说明系统自带、Homebrew、conda 三套并存，选哪一套直接决定后面pip装到哪去。我的习惯是统一用一个明确的版本号命令，比如python3.10，而不是笼统的python3，少一次猜谜。

提示：不要用系统自带的 Python 装第三方库。macOS 的系统 Python 和部分 Linux 发行版的/usr/bin/python3受系统包管理器管理，往里装东西轻则和系统工具冲突，重则把包管理器弄坏。

2.2 虚拟环境创建与激活：三个平台的命令差异

虚拟环境这一步没有技术含量，但翻车率极高，因为激活命令在不同 shell 里完全不一样。先在项目根目录建环境：

# 在项目目录下执行，.venv 是环境目录名，用点开头方便被 git 忽略 python3.10 -m venv .venv # 确认环境里带的 pip 是新的，旧 pip 会挑不到最新轮子 .venv/bin/python -m pip install --upgrade pip

Windows 上的创建命令把python3.10换成py -3.10即可，其余一致。激活分三种情况：

# macOS / Linux（bash、zsh 都适用） source .venv/bin/activate # Windows PowerShell .\.venv\Scripts\Activate.ps1 # Windows CMD .venv\Scripts\activate.bat

激活成功的标志是命令行提示符前面多出(.venv)。如果 PowerShell 报「无法加载文件，因为在此系统上禁止运行脚本」，那不是环境坏了，是执行策略拦住了，用Set-ExecutionPolicy -Scope CurrentUser RemoteSigned放开当前用户，再重新激活；不想改策略就直接用 CMD。

这里有个容易忽略的点：激活只是把.venv里的python和pip放到 PATH 最前面，如果你在 IDE 里跑代码，IDE 不一定认这个激活状态，得在项目设置里手动指到.venv/bin/python（Windows 是.venv\Scripts\python.exe）。我见过太多次「终端里能跑、IDE 里 ModuleNotFoundError」，全是这个原因。

2.3 安装 pygame：把版本范围写死，别裸装

装库这一步，我给的建议是不要pip install pygame一把梭。裸装拿到的是当时最新版，今天能跑，下个月重装可能就是另一个版本，行为差异全得重查一遍。用范围约束更稳：

# 装 2.5 到 2.6 之间的小版本，够新又不会跳到未知版本 .venv/bin/python -m pip install "pygame>=2.5,<2.7" # 网络不稳时走镜像，--index-url 只影响这一次安装 .venv/bin/python -m pip install "pygame>=2.5,<2.7" \ --index-url https://pypi.tuna.tsinghua.edu.cn/simple

用python -m pip而不是直接pip，是为了保证 pip 和当前解释器是同一套，这是虚拟环境里最常见的一类错装。装完立刻验证一次导入，别等到写完几百行代码才发现装错了地方：

.venv/bin/python -c "import pygame, sys; print(sys.executable); print(pygame.version.ver)"

第一行打出的是解释器路径，必须是.venv里的那个；第二行是 Pygame 版本。两行都对，环境这关就算过了。Linux 上如果这一步报编译错误、日志里出现SDL.h: No such file，说明 pip 没找到 wheel 转去源码编译了，先确认解释器版本是不是太新，实在不行装 SDL 开发包libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev再重试。

2.4 依赖固化与目录骨架：给下次重装留后悔药

环境能跑之后，立刻冻结依赖。这份requirements.txt就是下次重装时的后悔药：

# 只导出顶层依赖，不锁死传递依赖，跨平台迁移更友好 .venv/bin/python -m pip freeze > requirements.txt

文件里应该只有一行pygame==2.5.2这样的记录。以后换机器，建好虚拟环境执行pip install -r requirements.txt就还原了。

目录结构建议一开始就定死，别等文件堆起来再理：

# 三条命令建好骨架，assets 放素材，src 放代码 mkdir -p assets touch main.py requirements.txt .gitignore # .gitignore 里至少这几行，虚拟环境和缓存不进仓库 printf '.venv/\n__pycache__/\n*.pyc\n' > .gitignore

assets目录专门放背景音乐和以后可能加的字体文件，代码里所有素材路径都从项目根目录出发拼，不写../这种相对跳转。这个约定看着小题大做，但等你在 IDE、终端、双击运行三种方式之间来回切的时候，就知道它值多少钱了。

3. 代码骨架：Particle 与 Firework 两个类的具体写法

拿到手的代码示例常常是「被吃掉了缩进和属性访问」的版本，self.x变成self x，pygame.draw.circle变成p y game.draw.circle，直接复制粘贴必然SyntaxError。与其一行行改，不如按类的职责重新敲一遍，敲的过程本身就是在理解粒子系统的结构。

3.1 常量与入口：先把窗口尺寸和帧率钉死

窗口尺寸和帧率是全局约定，散落在各个类里会很难改。统一放在文件顶部：

import math import random from pathlib import Path import pygame # 全局常量集中定义，改分辨率只改这里 SCREEN_WIDTH, SCREEN_HEIGHT = 800, 600 FPS = 60 WHITE = (255, 255, 255) BLACK = (0, 0, 0) EXPLOSION_COLORS = [(255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 200, 0)] # 素材目录基于当前文件位置推导，不依赖运行目录 BASE_DIR = Path(__file__).resolve().parent MUSIC_PATH = BASE_DIR / "assets" / "new_year.ogg"

Path(__file__).resolve().parent这一句是关键：它拿的是main.py所在的绝对目录，不管你从哪个工作目录启动脚本，MUSIC_PATH都指向同一个文件。用os.getcwd()或者裸相对路径"assets/new_year.ogg"的做法，在双击运行和终端运行下结果不同，这是黑屏事故的高发点之一。

FPS定 60 不是玄学，clock.tick(60)会把主循环卡在每秒 60 帧，粒子运动的视觉速度才稳定。定 30 帧也能跑，但爆炸瞬间的扩散会明显发顿；定 120 帧对烟花这种场景没有收益，反而让每一帧的粒子计算量翻倍。

3.2 Particle 类：四个属性决定一颗火星能飞多远

粒子是这套效果的最小单元，属性一共就六个，但每个都影响观感：

class Particle: def __init__(self, x, y, color): self.x = float(x) # 位置用浮点，整数会在慢速时抖成台阶 self.y = float(y) self.color = color self.size = random.randint(4, 7) # 像素半径，4~7 肉眼刚好 self.life = 25 # 生命周期，单位是帧，不是秒 self.angle = random.uniform(0, 2 * math.pi) # 全圆均匀分布 self.speed = random.uniform(2, 5) # 每帧位移像素数 def move(self): self.x += self.speed * math.cos(self.angle) self.y -= self.speed * math.sin(self.angle) # y 轴向下为正，所以减 self.life -= 1 self.speed *= 0.95 # 阻尼系数，模拟空气阻力 def draw(self, screen): if self.life > 0: pygame.draw.circle( screen, self.color, (int(self.x), int(self.y)), self.size )

y方向用减号是 Pygame 坐标系决定的，屏幕左上角是原点，向下是正方向。这一点搞反，烟花会往地里钻，而且不报任何错。

life和speed的配合决定观感：life=25加上每帧speed乘 0.95 的阻尼，一颗粒子大概飞二十多帧后停住，视觉上就是「炸开、扩散、慢慢停、消失」。想让烟花更炸裂，把speed上限从 5 提到 8；想让它更飘，把阻尼从 0.95 改成 0.97。改这两个数比改粒子数量更有效，因为数量上去只是变密，运动曲线没变。

draw里的int()转换不能省。Pygame 2 的部分绘图函数对浮点坐标有兼容处理，但圆心的圆心参数在旧版本会直接抛TypeError，统一转成整数最省事。

3.3 Firework 类：发射、爆炸和粒子回收的时序

Firework管的是「一发烟花」的完整生命周期：先是一个上升的白点，到顶之后炸成一百个彩色粒子，粒子全部消亡后这个对象就该被回收。

class Firework: def __init__(self): self.particles = [] self.explosion_color = random.choice(EXPLOSION_COLORS) def launch(self): # 从屏幕底部随机横向位置升空，颜色固定白色，和爆炸颜色区分开 self.particles.append( Particle(random.randint(0, SCREEN_WIDTH), SCREEN_HEIGHT, WHITE) ) def explode(self): if not self.particles: return head = self.particles[0] for _ in range(100): # 单次爆炸的粒子数 self.particles.append( Particle(head.x, head.y, self.explosion_color) ) del self.particles[0] # 移除上升阶段的那个点 def update(self, screen): if not self.particles: return False # 通知主循环可以回收自己 # 用切片复制一份再遍历，边遍历边删才安全 for particle in self.particles[:]: particle.move() particle.draw(screen) if particle.life <= 0: self.particles.remove(particle) # 只剩一个粒子且已经升到屏幕上方，触发爆炸 if len(self.particles) == 1 and self.particles[0].y < 100: self.explode() return True

self.particles[:]这个切片是最容易被新手删掉的一行，删掉之后运行时报IndexError: list index out of range或者部分粒子永远不消失。原因很简单：列表在遍历过程中被remove修改，迭代器索引会错位。用切片复制一份，遍历的是副本，删的是原列表，互不干扰。这是 Python 里处理「边遍历边删」的通用写法，放到别的地方也成立。

len(self.particles) == 1这个判断条件的意思是「上升阶段只剩那个白点」，一旦爆炸，列表长度会瞬间变成 100，条件不再成立，不会重复爆炸。y < 100是引爆高度，值越小烟花飞得越高，超过屏幕顶部会看不见，所以别低于 50。

3.4 主循环：事件、更新、渲染三段的顺序不能换

主循环负责把上面两个类串起来，顺序固定：先处理事件，再更新状态并绘制，最后flip()提交画面。

def main(): pygame.init() # 初始化所有子模块 try: pygame.mixer.init() # 音频单独初始化，失败不算致命 pygame.mixer.music.load(str(MUSIC_PATH)) pygame.mixer.music.set_volume(0.5) pygame.mixer.music.play(-1) # -1 表示无限循环 except pygame.error as exc: print(f"音频不可用，静音运行: {exc}") screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT)) pygame.display.set_caption("Happy New Year") clock = pygame.time.Clock() fireworks = [Firework()] fireworks[-1].launch() running = True while running: for event in pygame.event.get(): if event.type == pygame.QUIT: running = False elif event.type == pygame.KEYDOWN and event.key == pygame.K_SPACE: fw = Firework() # 空格手动加一发 fw.launch() fireworks.append(fw) screen.fill(BLACK) # 每帧先清屏，否则全是拖影 for fw in fireworks[:]: if not fw.update(screen): fireworks.remove(fw) if random.random() < 0.05: # 每帧 5% 概率自动补一发 fw = Firework() fw.launch() fireworks.append(fw) pygame.display.flip() clock.tick(FPS) pygame.quit() if __name__ == "__main__": main()

screen.fill(BLACK)放在绘制之前，这是动画的基本规矩。省掉这一行，每一帧都画在上一帧上，屏幕上会留出长长的白色拖尾，看起来像卡死，其实只是没清背景。

random.random() < 0.05是按帧算的概率，60 帧乘下来大约是每秒 3 发，比原文注释里写的 5 发要稀一点，实测这个密度画面不糊。想更热闹就改到 0.08，别超过 0.15，否则几百个粒子同时飞，帧率会往下掉。

pygame.mixer那一整段包在try里是刻意的：音频设备在服务器、远程桌面、部分虚拟机里根本不存在，初始化失败会抛pygame.error，如果不接住，整个程序连窗口都开不起来。烟花能看是主要目的，有声音是加分项，主次不能倒过来。

4. 音效接入：mixer 初始化参数与素材格式选择

背景音乐是这套效果里最容易出问题的一环，因为它同时受音频设备、文件格式、mixer初始化三方面影响，出错信息还特别含糊。

4.1 pre_init：在 init 之前把参数定下来

pygame.mixer.init()内部会按默认参数打开音频设备，默认值是频率 44100、位深 -16、双声道、缓冲区 512。如果你的mixer在初始化之后才改参数，改动是不生效的——必须先调pre_init：

# 必须在 pygame.mixer.init() 之前调用，顺序反了参数全被忽略 pygame.mixer.pre_init(frequency=44100, size=-16, channels=2, buffer=512) pygame.init() pygame.mixer.init()

四个参数的含义：frequency采样率，44100 是 CD 标准，一般不动；size位深，-16表示有符号 16 位，负号不能丢；channels=2是立体声，改 1 就变单声道；buffer是音频缓冲区大小，512 延迟低但容易爆音，1024 更稳但按键音效会有轻微延迟。烟花场景对延迟不敏感，真遇到爆音就把buffer调到 1024。

pygame.init()并不保证mixer初始化成功，它会返回一个(成功数, 失败数)的元组，失败的子模块被静默跳过。所以单独再调一次mixer.init()并捕获异常，是为了拿到明确的错误信息，而不是让程序在半初始化状态下跑。

4.2 音乐格式：mp3 能放，但不建议放

SDL_mixer 对 mp3 的支持是「能解码，但看运气」，不同平台打包的解码库版本不一样，同一份 mp3 在 Windows 上能放、在 macOS 上直接pygame.error: Error reading the audio data。工程上的稳妥做法是转成 ogg 或 wav：

# 用 ffmpeg 转一道，音质损失可忽略，兼容性提升明显 ffmpeg -i source.mp3 -c:a libvorbis -q:a 4 assets/new_year.ogg # 短音效直接转 wav 更省心，不需要额外解码库 ffmpeg -i boom.mp3 -ar 44100 -ac 2 assets/boom.wav

ogg 适合长时间循环的背景音乐，体积比 wav 小一个数量级；wav 适合短促的爆炸音效，加载快、解码零依赖。循环播放用play(-1)，只播一次用play()，别传 0——play(0)在某些版本里等同于「不播放」。

4.3 素材缺失时的降级写法

素材文件是外部依赖，随时可能被删、被改名、被.gitignore漏掉。代码里要做的是「发现没有就跳过」，而不是让它抛异常把整个程序带走：

# 先判断文件存在再加载，缺素材时静音但画面照常 if MUSIC_PATH.exists(): pygame.mixer.music.load(str(MUSIC_PATH)) pygame.mixer.music.set_volume(0.5) pygame.mixer.music.play(-1) else: print(f"未找到音乐文件 {MUSIC_PATH}，静音运行")

str(MUSIC_PATH)这个转换别省。pygame.mixer.music.load接收的是字符串路径，直接传Path对象在部分 Pygame 版本上会报TypeError: expected str, bytes or os.PathLike object。统一转字符串，跨版本都安全。

另外要注意素材路径里不要出现中文和空格。Pygame 底层走的是 SDL 的 C 接口，某些平台对非 ASCII 路径处理不一致，表现是「文件明明在，就是加载失败」。项目目录用全英文，是最省事的规避方式。

5. 排查手册：烟花跑不起来的五个翻车现场

下面这五条，是我在不同机器上重复遇到过的问题，按「从装到跑」的顺序排。每条都给现象、原因、解决三部分，对号入座比读文档快。

5.1 导入就报 ModuleNotFoundError: No module named 'pygame'

现象：终端里pip install pygame明明显示 Successfully installed，运行python main.py还是报找不到模块。

原因：pip和python不是同一套解释器。机器上同时存在系统 Python、Homebrew Python、conda Python 时，pip可能指向 A，而python指向 B，装到 A 里的库当然找不到。

解决：先把两个路径打出来对一下：

python -c "import sys; print(sys.executable)" pip -V # 输出里带着 pip 所属的 python 路径

两条路径的目录部分不一致，就是这个病。统一用python -m pip install pygame重装，或者直接激活虚拟环境后执行.venv/bin/python -m pip install pygame。装完再python -c "import pygame"验证一次，别靠记忆。

5.2 pygame.error: video system not initialized

现象：脚本启动瞬间就崩在这一行，窗口都没弹出来。

原因有三种。一是代码里在pygame.display.set_mode()之前调用了display.flip()或event.get()；二是pygame.quit()之后又进了循环；三是在没有图形界面的环境里跑（远程 SSH、容器内），根本没显示设备。

解决：检查main()里的顺序，pygame.init()和set_mode()必须在任何绘制之前。远程环境里想跑通，加一个虚拟显示驱动：

# 只在无显示器的环境里用，本地开发别加 SDL_VIDEODRIVER=dummy .venv/bin/python main.py

这个模式下看不到画面，只能用来看程序有没有崩溃、日志有没有报错，验证视觉效果还得在本地机器上。

5.3 mixer 报 No available audio device

现象：画面正常，但启动时打出一串ALSA lib pcm.c的警告，紧接着pygame.error: No available audio device，程序直接退出。

原因：机器上没有任何可用音频输出设备。常见于容器、云主机、只有远程桌面的环境，或者 Linux 上 PulseAudio 没起来。mixer.init()拿不到设备就抛异常，没接住就整个崩。

解决：分两步。代码上，把mixer初始化包进try/except pygame.error，失败就静音继续跑，这是第 3.4 节已经写好的写法。环境上，如果只是要验证逻辑，可以指定虚拟音频驱动：

# 用 dummy 音频驱动跳过真实声卡，程序能完整跑流程 SDL_AUDIODRIVER=dummy .venv/bin/python main.py

本地有真声卡却报这个错，多半是mixer.pre_init里channels或frequency设了设备不支持的值，改成 44100 / 2 声道再试。

5.4 程序不报错，但屏幕全黑

现象：窗口正常弹出，标题栏正确，等了十几秒什么都没出现，进程也没退出。

原因：最常见的是screen.fill(BLACK)写在了绘制之后，把刚画好的粒子又擦掉了。其次是粒子初始位置在屏幕外面——Particle的y传了SCREEN_HEIGHT但move里写成了+=，粒子往下飞，永远进不了画面。还有一种是背景音乐路径含中文，load抛异常后代码没接住，主循环压根没进。

解决：在黑屏状态按空格键，如果有烟花出现，说明主循环是活的，问题在自动生成那段；如果按空格也没反应，查random.random()那个分支是不是被return提前截断了。再退一步，在while循环里临时加一行print(clock.get_fps())，能打出来就说明循环在转，问题在绘制。

5.5 跑几十秒后越来越卡

现象：刚启动 60 帧很流畅，半分钟后明显掉帧，一两分钟后风扇狂转。

原因：粒子对象泄漏。Firework.update()里如果没有正确remove掉生命周期结束的粒子，列表会一直增长，每帧都要遍历几千个已经不该存在于屏幕上的对象。

解决：在update里加一行计数，跑十秒后打印一次：

# 临时调试，确认粒子总数是否失控，调完删掉 total = sum(len(fw.particles) for fw in fireworks) print(f"活跃烟花 {len(fireworks)} 组，粒子 {total} 个")

正常运行时粒子总数应该在一百到几百之间波动。如果这个数字持续单调上涨，说明particle.life <= 0的删除分支没生效，检查是不是在for particle in self.particles:上直接遍历并删除——改成切片副本self.particles[:]。另外fireworks列表本身也要清理，update()返回False时必须从列表里删掉，否则空壳对象会一直堆着。

6. 跑通自查：三分钟确认这套环境真的能用

代码拼完先别急着欣赏效果，用一个小脚本把环境信息全打出来，出问题时这份输出就是唯一的黑匣子：

# check_env.py：一分钟体检，出问题先看这里的输出 import sys import pygame print("python :", sys.version.split()[0]) print("exe :", sys.executable) print("pygame :", pygame.version.ver) print("sdl :", pygame.version.SDL) pygame.init() pygame.display.set_mode((320, 240)) print("display:", pygame.display.get_driver()) # 正常是 windows / x11 / cocao try: pygame.mixer.init() print("mixer :", pygame.mixer.get_init()) # 正常形如 (44100, -16, 2) except pygame.error as exc: print("mixer : 不可用 ->", exc) pygame.quit()

四项信息各有含义：exe对不上虚拟环境就是装错地方；pygame版本超出 2.5~2.6 说明有人手动升级过；display打出dummy说明环境变量被设置过；mixer那行能打出元组就代表声卡可用。

接着跑主程序，重点看三件事：窗口是不是 800×600、按空格键能不能追加一发烟花、左上角用clock.get_fps()打出来的帧率是不是稳定在 60 附近。三件都过，这套环境就算装成了。

画质参数我一般留三档备忘，按机器性能选，不用来回试：

改这三个数只需要动explode()里的range(100)、Particle的life、主循环里的0.05，其余代码不用碰。我见过有人为了更炸裂直接把粒子数写到 500，结果帧率掉到 15，画面比原来还糊——粒子的视觉密度靠的是运动曲线，不是数量。

从那以后我每次装完这类图形库，都会先跑一遍体检脚本、再按空格键确认交互是活的，最后才去看效果好不好。环境问题在信息齐全的时候，一眼就能定位；信息不全的时候，就得靠一晚上瞎猜。按上面的顺序走一遍，能省掉这一晚。希望帮到你。

本文还有配套的精品资源，点击获取