简介：一份面向Python初学者与图形编程爱好者的实践型文档，围绕Pygame库讲解新年烟花动画的完整实现路径，帮助读者在节日场景中理解窗口绘制、帧循环与交互事件处理。压缩包内仅含1个docx文件，大小约16KB，篇幅集中，便于快速通读与本地复现。内容从环境准备与pip安装讲起，依次拆解Particle粒子类、Firework发射器类以及主循环中的随机生成、爆炸判定和键盘触发逻辑，并给出可直接运行的代码示例；同时涉及背景音乐加载、颜色配置、粒子数量与发射频率等可调参数，读者可据此改造出个人化烟花展示。已有143人学习，适合希望以小型项目入门Pygame、掌握基础图形界面应用开发的学习者参考。

1. 环境先列清：Pygame 2.x 的烟花动画，八成翻车在装库而不是写算法

用 Python 和 Pygame 库做新年烟花动画，是每年跨年前后被搜得最多的一类小项目，代码不长，粒子系统的公式也就三角函数那几行。但真正把人卡住的地方，几乎从来不是算法：窗口建出来是纯黑、音乐一声没有、pygame.error: mixer not initialized直接打断启动、装完pip install pygame却提示ModuleNotFoundError——全是环境和依赖的事。这套东西对新手友好、对老手也算顺手，但它的坑集中在安装和初始化阶段，装不对就是看黑屏。下面按一台干净机器的顺序走一遍：解释器怎么选、依赖装哪几个包、配置项写在哪、跑不起来怎么救。

2. 装 Python 与 Pygame：先对齐版本，再谈 pip install

2.1 解释器版本和预编译轮子的对应关系

Pygame 装不上的第一大原因不是网速，是解释器版本和轮子（wheel）对不上。Pygame 2.x 在主流平台上提供预编译轮子，匹配上就直接解压安装，匹配不上 pip 就去下源码包，然后要求本机有 C 编译器和 SDL 头文件，这一步能劝退大部分人。

我一般按下面这张表判断，先确认能不能走预编译路线：

几条实践经验：第一，别用系统自带的 Python 直接装库，尤其是 macOS 和某些 Linux 发行版，系统 Python 被包管理器管着，pip install会报externally-managed-environment；第二，32 位解释器在 Windows 上经常缺轮子，装之前先看python -c "import platform; print(platform.architecture())"输出是不是 64bit；第三，Pygame 的版本尽量跟着 Python 走，新解释器配老 Pygame 是最容易出问题的组合。

装之前先把 pip 本身升一下，老 pip 不认识新的 wheel 标签，会出现「明明有轮子却去编译源码」的怪现象：

# 升级 pip、setuptools、wheel 三件套，避免旧 pip 认不出新 wheel 标签 python -m pip install --upgrade pip setuptools wheel

这里用python -m pip而不是直接敲pip，是为了保证 pip 和当前解释器是同一个。机器上装了多个 Python 时，裸pip很可能指向另一个解释器，装完 import 不到，这个坑后面还会细说。

2.2 venv 隔离环境与镜像源安装

烟花项目依赖极简，但它有个特点：你可能同时在做别的 Pygame 小实验，版本互相污染的概率不低。所以我一般强制走 venv，成本几秒钟，省掉后面所有的「昨天还能跑」。

# 1. 在项目根目录创建虚拟环境，目录名用 .venv，IDE 一般能自动识别 python -m venv .venv # 2. 激活环境 # Windows（cmd / PowerShell） .venv\Scripts\activate # macOS / Linux source .venv/bin/activate # 3. 确认当前解释器确实指向 .venv 里的那个 python -c "import sys; print(sys.executable)" # 4. 在激活状态下安装 Pygame python -m pip install pygame

几个参数和动作的含义：python -m venv .venv里的.venv是目录名，点开头是为了让编辑器默认折叠、也避开部分工具的扫描；激活后提示符前会出现(.venv)，这是判断有没有激活成功最快的办法；第 3 步打印的路径里必须包含.venv，不包含就说明激活没生效或者 shell 配置劫持了 PATH。

国内网络环境下pip install pygame卡在下载阶段很常见，换镜像源的标准写法是：

# 临时指定镜像源，不写进全局配置，适合只装一次的场景 python -m pip install pygame -i https://<你的镜像源地址>/simple --trusted-host <你的镜像源地址>

-i指定索引地址，--trusted-host是给走 HTTP 的镜像源放行证书校验，换成 HTTPS 源时可以省掉。想长期生效就写进pip.ini（Windows）或~/.pip/pip.conf（Linux/macOS）的[global]段，把index-url和trusted-host两行配好。注意别把镜像源地址硬编码进代码里，那是环境配置，不是项目配置。

装完立刻验证一次，别等到写代码时才发现问题：

# 打印 Pygame 版本和 SDL 版本，能出来就说明 Python 层装好了 python -c "import pygame; print(pygame.version.ver); print(pygame.version.SDL)"

2.3 Linux / macOS / Windows 的图形与音频依赖

这是最容易被跳过的一步。Pygame 的 wheel 里已经打包了 SDL2 的库文件，Windows 和 macOS 上通常开箱即用；Linux 上如果装的是发行版打包的 Pygame，或者跑在没装桌面环境的服务器上，就会出问题。

Linux 桌面环境一般只需要确认这几个运行时库在：

# Debian / Ubuntu 系：SDL2 的图形、音频、字体、图像四个模块 sudo apt install -y libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-mixer-2.0-0 libsdl2-ttf-2.0-0 # 验证 SDL_mixer 是否真的装上了，烟花项目的音乐全靠它 ldconfig -p | grep -i mixer

libsdl2-mixer是音频子系统的核心，缺了它pygame.mixer.init()会抛错，但pygame.init()本身可能不报错，于是现象变成「窗口正常、就是没声音」，很难往依赖上想。libsdl2-ttf是字体模块，要在窗口上画 FPS 数字就得有它。

如果是在没有显示器的机器上跑（远程服务器、CI 环境），必须先设两个环境变量，否则初始化直接失败：

# 无头模式：不创建真实窗口、不占用声卡，用假驱动跑逻辑 export SDL_VIDEODRIVER=dummy export SDL_AUDIODRIVER=dummy

dummy驱动不渲染任何东西，适合做冒烟测试和帧率统计，正式看效果还是得在有桌面的机器上跑。macOS 上如果遇到pygame.error: No available video device，多半是在 SSH 会话里跑的，同样的处理方式。

3. 工程骨架与配置：把音乐路径、屏幕参数先抽出来

3.1 目录结构与常量集中管理

烟花项目最常见的坏味道是把screen_width、screen_height、音乐路径散落在代码各处，改一个分辨率要翻五个地方。我习惯在文件头部把可调项全抽成常量，后面调手感只改这一块。

# config.py —— 所有可调参数集中在这里，改效果不用翻业务代码 SCREEN_WIDTH = 800 # 窗口宽度，和屏幕高度一起决定粒子活动范围 SCREEN_HEIGHT = 600 # 窗口高度 FPS = 60 # 主循环帧率上限 PARTICLE_PER_BURST = 100 # 每次爆炸生成的粒子数，100 是流畅与观感的平衡点 SPAWN_CHANCE = 0.05 # 每帧自动发射新烟花的概率，约等于每秒 3 次 MUSIC_PATH = "assets/bgm.ogg" # 相对项目根目录，别用绝对路径

参数说明：FPS是给clock.tick()的上限，不是保证值，机器性能不够时会掉；PARTICLE_PER_BURST是单个烟花的粒子总数，100 个粒子 × 同时 10 朵烟花 = 1000 个圆，这是 800×600 分辨率下比较舒服的量级；SPAWN_CHANCE按 60 帧算，0.05 大约对应每秒 3 朵，想更热闹往上调，但别超过 0.15，否则粒子数会失控；MUSIC_PATH用相对路径，启动时的工作目录必须是项目根目录，这一条后面排查章还会提到。

目录结构我一般这样摆，简单但够用：

fireworks/ ├── main.py # 入口，主循环 ├── config.py # 常量配置 ├── particle.py # Particle 粒子类 ├── firework.py # Firework 发射器类 └── assets/ └── bgm.ogg # 背景音乐

拆文件的理由不是「工程规范」，是粒子调参时你会在particle.py里反复改数字，和主循环混在一个文件里改起来很费眼。小项目也一样。

3.2 mixer 的 pre_init 与音乐加载的容错

Pygame 的音频初始化有个顺序要求：pygame.mixer.pre_init()必须在pygame.init()之前调用，否则参数不生效。pre_init设的是采样率、位深、声道数和缓冲区大小，缓冲区越小延迟越低，但太小会爆音。

import os import pygame # pre_init 必须在 pygame.init() 之前，参数才生效 pygame.mixer.pre_init(frequency=44100, size=-16, channels=2, buffer=512) pygame.init() def load_music(path): """加载背景音乐，失败时返回 False 而不是抛异常打断程序""" if not os.path.exists(path): print(f"[warn] 音乐文件不存在: {path}") return False try: pygame.mixer.music.load(path) pygame.mixer.music.set_volume(0.6) # 0.0~1.0，别一上来就是 1.0 pygame.mixer.music.play(-1) # -1 表示无限循环 return True except pygame.error as e: # 常见于 mp3 解码器缺失、文件损坏、格式不被 SDL_mixer 支持 print(f"[warn] 音乐加载失败，静音继续: {e}") return False

逻辑说明：size=-16表示 16 位有符号采样，这是兼容性最好的配置；channels=2是立体声，改成 1 会变成单声道，音质下降但占用更低；buffer=512是缓冲区帧数，44100Hz 下约 11ms，比默认值跟手很多。函数返回布尔值而不是让异常往上冒，是因为音乐只是「增强体验」，不该成为程序跑不起来的理由——这是烟花项目最实际的一条设计取舍。

格式上有个血泪经验：优先用.ogg或.wav，别默认用.mp3。部分平台的 SDL_mixer 编译时没带 mp3 解码器，music.load()会抛pygame.error: Couldn't open ...，而网上流传的代码清一色写 mp3 路径。转格式用ffmpeg -i bgm.mp3 bgm.ogg一条命令的事。

3.3 窗口、时钟与双缓冲参数

窗口创建看着简单，但参数选错会出现撕裂、黑边、拉伸。Pygame 2 里set_mode的第二个参数是标志位组合：

screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT)) pygame.display.set_caption("New Year Fireworks") # 时钟对象，全篇只用这一个，别在循环里反复 new clock = pygame.time.Clock()

参数取舍：默认的set_mode已经开了双缓冲，日常够用；如果要做全屏或缩放，可以传pygame.SCALED，让 Pygame 自己处理高 DPI 缩放，避免在 4K 屏上窗口小得像邮票；pygame.HWSURFACE只在全屏下有意义，窗口模式下加了也白加。set_caption是窗口标题，中文标题在部分系统上会显示成方块，那就老老实实写英文。

clock.tick(FPS)有两个作用：限制帧率、返回上一帧耗时（毫秒）。第二点很多人不用，但它是做平滑动画的关键——用固定步长在低帧率机器上会变慢，用dt驱动则不会：

dt = clock.tick(FPS) / 1000.0 # 转成秒，典型值 0.016

dt后面会传给粒子的移动方法，速度乘以dt才是「每秒移动多少像素」，这样 30 帧和 60 帧的观感一致。不乘dt的代码在性能差的机器上会明显变慢，这是粒子动画最常见的隐形 bug。

4. 粒子与发射器落地：两个类的参数怎么调

4.1 Particle：life、speed、size 与 dt 驱动的写法

Particle类负责单个粒子的位置、速度、角度、生命周期。原始写法用固定递减的life，我一般改成用秒计算的浮点生命周期，配合dt更稳。

import math import random import pygame class Particle: def __init__(self, x, y, color): self.x = float(x) self.y = float(y) self.color = color self.size = random.randint(2, 4) # 半径，2~4 像素 self.life = random.uniform(0.8, 1.6) # 存活秒数 self.max_life = self.life # 记下初始值，用于算透明度 self.angle = random.uniform(0, 2 * math.pi) # 抛射角度，整圆均匀分布 self.speed = random.uniform(80, 220) # 像素/秒 def move(self, dt, gravity=180): # 速度按角度分解成 x/y 分量，y 轴向上为正，所以要减去 self.x += self.speed * math.cos(self.angle) * dt self.y -= self.speed * math.sin(self.angle) * dt self.speed *= 0.98 # 空气阻力，每帧衰减 2% self.y += gravity * dt * dt # 重力只作用在 y 上，二次项更接近真实下落 self.life -= dt def draw(self, surface): if self.life > 0: pygame.draw.circle( surface, self.color, (int(self.x), int(self.y)), self.size )

参数说明与调参手感：speed的 80~220 是像素/秒，数值越大爆炸范围越散，800×600 窗口下超过 300 就会飞出屏幕；life的 0.8~1.6 秒决定粒子在空中停留多久，短了像火花一闪，长了会积累大量残留粒子拖慢帧率；size的 2~4 像素，超过 5 就成糊状光斑，缺少颗粒感；speed *= 0.98这个衰减系数每帧执行一次，60 帧下大约 1 秒衰减到原来的 30%，接近真实爆炸的初速衰减曲线，改成 0.95 会「刹得太急」，改 0.99 则散得太远。

重力项gravity * dt * dt里的dt是平方，这是从加速度公式s = ½at²简化来的，量级上比dt小很多，所以gravity=180这个值看着不大但效果明显。想表现「烟花下坠」就调大，想表现「太空失重」就设 0。

4.2 Firework：上升粒子与爆炸的索引陷阱

Firework管理一组粒子：第一个是向上飞行的「弹体」，飞到一定高度后炸开成 100 个彩色粒子。这里有个经典陷阱——爆炸时要读particles[0]的坐标，然后把这个弹体删掉，顺序搞反就是IndexError。

class Firework: def __init__(self): self.particles = [] self.explosion_color = random.choice([ (255, 60, 60), (60, 200, 255), (255, 220, 80), (200, 120, 255) ]) def launch(self): # 从屏幕底部随机位置升空，颜色用白色做上升拖尾 x = random.randint(0, 800) self.particles.append(Particle(x, 600, (255, 255, 255))) def explode(self): # 关键：先取坐标，再生成新粒子，最后才删除原弹体 if not self.particles: return # 空列表直接返回，别硬取 [0] origin = self.particles[0] for _ in range(100): self.particles.append( Particle(origin.x, origin.y, self.explosion_color) ) del self.particles[0] # 删除必须在循环之后 def update(self, dt): for p in self.particles[:]: # 用切片副本遍历，边删边遍历会漏元素 p.move(dt) p.draw(surface) if p.life <= 0: self.particles.remove(p) # 弹体飞到屏幕 1/3 高度处就引爆，写成纯随机高度会更自然 if len(self.particles) == 1 and self.particles[0].y < 600 * 0.35: self.explode() return len(self.particles) > 0

三个关键点。第一，if not self.particles: return这个判空不能省，同一个烟花被update调两次就会踩到。第二，del self.particles[0]必须在生成爆炸粒子的循环之后，因为循环里要反复读origin.x；如果先删，origin变成悬空引用，坐标虽然还在但列表长度全乱。第三，遍历self.particles[:]是复制一份浅拷贝再遍历，直接遍历原列表同时remove会跳过元素——这是 Python 列表操作的通用坑，不是 Pygame 的。

爆炸高度600 * 0.35这个比例是手感值：太高会撞到顶部边框，太低炸在地面附近不好看。想做出层次感就用random.uniform(0.15, 0.45)让每朵烟花在不同高度炸开。

4.3 主循环：事件、更新与随机发射的节奏

主循环是三件事的循环：处理事件、更新状态、重绘屏幕。顺序错了就是黑屏或者卡顿。

fireworks = [Firework()] fireworks[-1].launch() # 先放一朵，避免开局空白 running = True while running: dt = clock.tick(FPS) / 1000.0 for event in pygame.event.get(): if event.type == pygame.QUIT: running = False elif event.type == pygame.KEYDOWN and event.key == pygame.K_SPACE: fireworks.append(Firework()) # 空格键手动放一朵 fireworks[-1].launch() screen.fill((0, 0, 0)) # 必须先清屏，不清屏就是全屏拖影 for fw in fireworks[:]: if not fw.update(dt): fireworks.remove(fw) if random.random() < 0.05: # 自动发射，和 config 里的 SPAWN_CHANCE 对应 fireworks.append(Firework()) fireworks[-1].launch() pygame.display.flip() # 双缓冲交换，最后一步

要点：screen.fill((0,0,0))每帧都要执行，漏掉就会出现「烟花拖成一道光带」的效果，早期很多人以为是特效，后来发现是没清屏；pygame.display.flip()是双缓冲的交换动作，必须在所有绘制之后、下一帧之前，漏掉就是永远的纯黑窗口；for fw in fireworks[:]同样用副本遍历，因为循环体里会remove。dt单独取一次放在循环顶部，所有更新都用同一个dt，保证同一帧内的一致性。

事件循环里只处理了QUIT和空格键，实际可以加ESC退出、F11全屏，但别在事件循环里做耗时操作（比如 load 音乐），那是掉帧的常见原因。

5. 排查：五种跑不起来的现象与救法

5.1 现象：ModuleNotFoundError: No module named 'pygame'

原因几乎只有一个：pip 装到了另一个解释器。装了 venv 但 IDE 没切过去、或者终端里激活了另一套环境，都会出现「明明装过」的错觉。

解决：先python -c "import sys; print(sys.executable)"看当前解释器路径，再用同一个解释器装：python -m pip install pygame。IDE 里要去设置里手动把解释器指向.venv/bin/python（Windows 是.venv\Scripts\python.exe）。装完用python -c "import pygame; print(pygame.version.ver)"复验，能打印版本号才算通。别用pip install pygame这种裸写法，多 Python 环境下它指向哪个是玄学。

5.2 现象：窗口建出来是纯黑，程序不报错也不退出

原因分两类：一是没有在循环末尾调pygame.display.flip()，绘制全在后台缓冲区里，屏幕永远看不到；二是主循环里抛了异常，但被外层的宽泛try吞掉了，进程还在但循环已经停了。

解决：先看有没有flip()或pygame.display.update()；再临时去掉所有try/except，让异常直接打到终端。常见被吞的异常是IndexError（粒子列表空了还在取下标）和AttributeError（变量名拼错）。另外确认screen.fill()确实在while里，而不是循环外只执行一次。

5.3 现象：pygame.error: video system not initialized 或 mixer not initialized

原因是没有初始化就调用了对应模块，或者初始化失败了但没检查返回值。pygame.init()会返回一个(成功数, 失败数)的元组，失败数不为 0 就说明有子模块挂了。

解决：确认pygame.init()在set_mode和mixer.music.load之前；Linux 上装齐libsdl2-mixer-2.0-0；无桌面环境必须设SDL_VIDEODRIVER=dummy。可以在init()后加一行print(pygame.init())，正常是(6, 0)或类似数字，第二个值大于 0 就照它去查对应模块。

5.4 现象：音乐不响，但没有任何报错

原因有三种：mp3 解码器缺失、路径是相对路径但工作目录不对、mixer.music.play()忘了调或传了0（播放 0 次就是不动）。

解决：把 mp3 换成 ogg 或 wav；把路径改成os.path.join(os.path.dirname(__file__), "assets/bgm.ogg")这种基于文件位置的绝对路径，避免从别的目录启动时找不到；确认play(-1)的参数是-1而不是0；再不行就print(pygame.mixer.get_init())，返回None说明音频子系统压根没起来。

5.5 现象：跑几十秒后帧率从 60 掉到个位数

原因是粒子泄漏：爆炸生成的粒子没有及时从列表里删除，或者烟花对象本身没被回收。life <= 0的判断用了固定值而不是dt递减，粒子永远死不掉。

解决：检查update里是否有if p.life <= 0: self.particles.remove(p)；检查Firework.update()返回值，返回False时主循环必须把整个烟花对象从fireworks列表里删掉；加个粒子总数上限，超过就停止发射新的。实测 1000 个pygame.draw.circle在 60 帧下还算稳，到 3000 个就明显掉帧，所以发射频率和粒子数要一起控制。

6. 装完怎么验证：从黑屏到稳定 60 帧的跑通清单

装完之后不要直接盯着窗口看效果，那只能验证「有画面」，验证不了「装对了」。我习惯先跑无头冒烟测试，用数字确认粒子系统、事件循环、帧率控制三件事都正常。

# smoke_test.py —— 无头跑 300 帧，统计粒子峰值和平均帧耗时 import os os.environ.setdefault("SDL_VIDEODRIVER", "dummy") os.environ.setdefault("SDL_AUDIODRIVER", "dummy") import time import pygame from config import SCREEN_WIDTH, SCREEN_HEIGHT from firework import Firework pygame.init() screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT)) clock = pygame.time.Clock() fireworks = [] peak = 0 t0 = time.perf_counter() for frame in range(300): dt = clock.tick(60) / 1000.0 screen.fill((0, 0, 0)) if frame % 12 == 0: # 每 12 帧放一朵，模拟真实发射节奏 fireworks.append(Firework()) fireworks[-1].launch() for fw in fireworks[:]: if not fw.update(dt): fireworks.remove(fw) peak = max(peak, sum(len(fw.particles) for fw in fireworks)) elapsed = time.perf_counter() - t0 print(f"总帧数: 300 耗时: {elapsed:.2f}s 平均帧耗时: {elapsed / 300 * 1000:.1f}ms") print(f"粒子峰值: {peak} 当前烟花数: {len(fireworks)}") pygame.quit()

这段脚本的几个设计点：环境变量用setdefault而不是直接赋值，是为了在有显示器的机器上仍然能正常看效果；clock.tick(60)会真的阻塞到 60 帧的节奏，所以「平均帧耗时」应该稳定在 16.6ms 左右，明显高于 20ms 就说明渲染有瓶颈；粒子峰值是判断有没有泄漏的核心指标，正常应该在几百到一千出头，跑到 3000 以上且不回落就是泄漏。

下面这张表是我每次装完都会对一遍的检查项：

想再稳一点，就在窗口左上角实时画 FPS，用pygame.font.SysFont("arial", 18).render(...)每帧更新一次。字体模块在 Linux 上依赖libsdl2-ttf，装漏了会报font not initialized，这一条也可以顺便当作依赖是否齐全的验收标准。

从那以后我每次装 Pygame 类项目，都强制走一遍「打印解释器路径 → 打印 pygame 版本 → 无头跑 300 帧」，三行输出贴出来，环境问题基本当场现形，不用等到跨年夜盯着黑屏干着急。希望这套顺序也能帮你少走几个弯路。

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