企业官网建设流程全解析

这次我们来看一个自己动手做的 Python 项目，名字叫大肥鱼。它不是一个需要 4090 的大模型工具，也不是复杂的云原生框架，而是一个基于 Pygame 的桌面互动程序：一条小鱼在窗口里游动，吃食物、变长变大，最后变成一条圆滚滚的大肥鱼。整个项目不依赖 GPU，不需要上显存，普通办公电脑就能跑，适合用来练习 Pygame 游戏循环、碰撞检测、事件处理和本地接口服务。

大肥鱼这个项目最值得关注的点有三个。第一是轻：只有一个 main.py 核心脚本加一个可选 API 脚本，依赖只有 Pygame。第二是有接口：单独运行 api_server.py 后，可以通过 HTTP 请求下发速度、食物数量等配置，游戏进程每次刷新时会读取本地 control.json，两个进程解耦，适合理解“本地进程 + API 控制”的基础架构。第三是能批量：支持用 SDL_VIDEODRIVER=dummy 的方式在无窗口环境下批量渲染 PNG 截图，方便后续做素材集或自动化演示。

这篇文章会带着你把大肥鱼跑起来，内容包括环境准备、代码结构、启动方式、功能测试、接口 API 调用、批量截图、资源占用观察和常见问题排查。如果你正想找一个“本地部署 + 接口控制 + 批量任务”的最小可实践项目，这篇可以直接收藏。

1. 核心能力速览

大肥鱼虽然是一个偏玩具性质的自制项目，但它把本地开发里经常遇到的几个关键点都覆盖到了：渲染循环、外部配置、接口服务、批处理脚本。先看整体能力：

从表格能看出来，大肥鱼不是一个追求画面表现力的项目，它的价值在于“麻雀虽小，五脏俱全”。你可以在它身上看到一套很典型的本地应用结构：一个渲染主程序，一个可选的 API 控制端，一个批量任务脚本。把这三块跑通之后，以后做其他桌面工具或本地服务，都可以复用这套思路。

项目的运行逻辑非常简单：窗口里有一条鱼和若干个金色食物，鱼通过方向键或 WASD 移动，碰到食物后食物消失、分数加一、鱼身半径增大。食物少于一定数量时会自动补充，避免画面空掉。按空格键暂停，按 ESC 或关闭窗口退出。核心代码量不大，非常适合用来做 Pygame 入门的完整范例。

2. 适用场景与使用边界

先说明适合谁。如果你是刚开始学 Python，想找一个能快速看到反馈的图形项目，大肥鱼比控制台猜数字直观得多。Pygame 的窗口、事件、帧率控制和碰撞检测都是游戏开发的基础概念，大肥鱼的代码把这几件事压缩在一个脚本里，容易读懂，也好拆开验证。如果你已经工作，想给团队做一个内部用的桌宠或者大屏展示小鱼动画，大肥鱼的代码也能直接改造。

如果你是做接口联调的，大肥鱼更适合当“活体测试对象”。它提供了一个独立的 API 服务，你可以在浏览器或 curl 里下发参数，然后观察主程序行为是否变化。这种“一个进程管理渲染、一个进程管理配置”的模式，和很多本地工具的实现思路是一致的，很有参考价值。

再说大肥鱼不适合什么。它不适合做商用级游戏，没有复杂动画、音效、物理引擎，也没有多人在线能力。它不适合做高并发服务，API 服务用的是 Python 标准库 HTTPServer，适合本机或内网小范围调用，不能直接暴露公网。它也不是 AI 项目，不涉及模型推理、训练、参数调优。

使用边界需要强调三点。第一，如果后续你给大肥鱼加了自定义鱼身贴图、背景音乐、音效素材，要注意素材版权。不要随便拿商业游戏或网络图片直接打包发布。第二，API 服务默认绑定 127.0.0.1，这是有意的安全设计。如果你把它改成 0.0.0.0，等于允许局域网内其他机器下发配置，在没有鉴权的条件下会有风险，建议只在可信内网测试。第三，批量截图、自动化模拟这类功能，只适合用于自己的测试环境和素材生产，不要用来做未经授权的采集或自动化操作。

3. 环境准备与前置条件

大肥鱼的依赖非常少，核心只有 Python 和 Pygame。建议使用 Python 3.8 以上版本，太老的版本对 Pygame 的 wheel 包支持不够好。先确认 Python 是否安装：

python --version

如果还没有安装 Python，去官网选择对应操作系统的安装包，安装时勾选“Add Python to PATH”。这一步做不好，后面命令行会找不到 python。

安装完 Python 后，强烈建议先用虚拟环境隔离项目依赖，避免和其他项目的包版本冲突。在项目目录下执行：

mkdir bigfish cd bigfish python -m venv venv

Windows 下激活虚拟环境：

venv\Scripts\activate

Linux 和 macOS 下激活：

source venv/bin/activate

激活后，命令行提示符前面会出现(venv)前缀，这说明当前已经进入虚拟环境。然后安装依赖：

pip install -U pip pip install pygame

如果觉得 Pygame 下载太慢，可以临时使用国内镜像源：

pip install pygame -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后可以用一行命令检查 Pygame 是否能正常导入：

python -c "import pygame; print(pygame.version.ver)"

如果正常打印版本号，说明环境基本就绪。大肥鱼不需要额外安装 CUDA 工具包、PyTorch、ComfyUI 等重组件，所以环境准备环节通常几分钟就能完成。

4. 安装部署与启动方式

大肥鱼的部署方式就是下载代码文件后运行。这里没有一键安装包，但所有代码放在单个目录里，结构非常简单：

bigfish/ ├── main.py # 主程序，负责窗口渲染和游戏逻辑 ├── api_server.py # 可选，HTTP 接口服务 ├── batch_screenshot.py # 可选，批量截图脚本 └── control.json # 运行时生成的配置文件

下面直接给出 main.py 的完整代码。这份代码是可运行的简化版本，重点在于演示大肥鱼的核心逻辑：

# main.py # 大肥鱼桌面互动程序：控制小鱼吃食物，越吃越大 import json import os import random import sys import pygame # 初始化 pygame.init() WIDTH, HEIGHT = 800, 600 screen = pygame.display.set_mode((WIDTH, HEIGHT)) pygame.display.set_caption("Big Fish - 大肥鱼") clock = pygame.time.Clock() # 颜色定义 BG = (20, 30, 48) WHITE = (255, 255, 255) DARK = (30, 30, 60) FOOD_COLOR = (255, 210, 90) def load_control(): """读取控制配置文件，可选功能。""" cfg = {"speed": 5, "food_count": 10} if os.path.exists("control.json"): try: with open("control.json", "r", encoding="utf-8") as f: cfg.update(json.load(f)) except Exception: pass return cfg class BigFish: """一条会吃食物长大的鱼。""" def __init__(self): self.x = WIDTH // 2 self.y = HEIGHT // 2 self.size = 30 # 初始身体半径 self.score = 0 self.speed = 5 def move(self, keys): dx = dy = 0 if keys[pygame.K_LEFT] or keys[pygame.K_a]: dx -= 1 if keys[pygame.K_RIGHT] or keys[pygame.K_d]: dx += 1 if keys[pygame.K_UP] or keys[pygame.K_w]: dy -= 1 if keys[pygame.K_DOWN] or keys[pygame.K_s]: dy += 1 if dx != 0 or dy != 0: norm = (dx ** 2 + dy ** 2) ** 0.5 self.x += dx / norm * self.speed self.y += dy / norm * self.speed # 限制在窗口内 self.x = max(self.size, min(WIDTH - self.size, self.x)) self.y = max(self.size, min(HEIGHT - self.size, self.y)) def draw(self, screen): # 身体 pygame.draw.ellipse( screen, (70, 140, 220), (self.x - self.size, self.y - self.size * 0.6, self.size * 2, self.size * 1.2) ) # 尾巴 tail_len = int(self.size * 1.2) pygame.draw.polygon( screen, (220, 80, 80), [ (self.x - self.size, self.y), (self.x - self.size - tail_len, self.y - tail_len // 2), (self.x - self.size - tail_len, self.y + tail_len // 2), ] ) # 眼睛 eye_r = max(4, self.size // 6) eye_x = self.x + int(self.size * 0.8) eye_y = self.y - int(self.size * 0.3) pygame.draw.circle(screen, WHITE, (eye_x, eye_y), eye_r) pygame.draw.circle(screen, DARK, (eye_x, eye_y), max(2, eye_r // 2)) def eat(self, foods): for food in foods[:]: dist = ((self.x - food[0]) ** 2 + (self.y - food[1]) ** 2) ** 0.5 if dist < self.size + food[2]: foods.remove(food) self.score += 1 self.size = min(120, self.size + 2) # 鱼最大半径 120 self.speed = max(3, self.speed - 0.15) # 变大后速度略降 def spawn_food(count=10): foods = [] for _ in range(count): r = random.randint(6, 14) foods.append([random.randint(r, WIDTH - r), random.randint(r, HEIGHT - r), r]) return foods def main(): fish = BigFish() cfg = load_control() fish.speed = cfg.get("speed", 5) foods = spawn_food(cfg.get("food_count", 10)) paused = False font = pygame.font.Font(None, 24) running = True while running: clock.tick(60) # 限制帧率约 60 FPS for event in pygame.event.get(): if event.type == pygame.QUIT: running = False if event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE: running = False if event.type == pygame.KEYDOWN and event.key == pygame.K_SPACE: paused = not paused if not paused: keys = pygame.key.get_pressed() fish.move(keys) fish.eat(foods) if len(foods) < 5: foods.extend(spawn_food(5)) screen.fill(BG) fish.draw(screen) for x, y, r in foods: pygame.draw.circle(screen, FOOD_COLOR, (x, y), r) tip = f"score: {fish.score} size: {fish.size:.0f} paused: {paused}" screen.blit(font.render(tip, True, WHITE), (10, 10)) pygame.display.flip() pygame.quit() sys.exit(0) if __name__ == "__main__": main()

把上面的代码保存为 main.py，然后在项目目录里运行：

python main.py

启动后应该出现一个深蓝色背景的窗口，里面有一条蓝色小鱼和若干个金色食物。初始状态下鱼不会自动移动，你需要用方向键或 WASD 控制它。当鱼碰到金色食物时，食物会消失，左上角分数加 1，鱼身半径明显变大。身体达到 120 像素上限后不再增大，这就是“大肥鱼”的最终形态。

窗口没有出现，或者启动后闪退，大概率是 Pygame 依赖没有安装成功，或者显卡驱动兼容性问题。可以先回到第 3 节检查 Pygame 版本输出。如果依赖没问题，尝试把窗口分辨率改小，比如把 WIDTH 和 HEIGHT 改成 640 和 480，排除显示驱动兼容问题。

5. 功能测试与效果验证

大肥鱼这种交互项目，不能只看代码能不能跑，还要按功能点逐项验证。下面是一套直接可用的测试流程。

5.1 启动验证

测试目的是确认渲染循环正常。运行python main.py后，观察窗口是否出现、背景是否为深蓝色、鱼和食物是否绘制成功、左上角是否有分数文本。

判断标准：窗口能保持打开，鱼和食物不闪烁，分数数字正常显示。如果窗口黑屏，可能是pygame.display.flip()没有执行，或者屏幕颜色填充位置不对。如果窗口一闪而过，检查 main.py 里的while running循环是否被意外退出。

5.2 键盘移动测试

测试方向键和 WASD。鱼朝按键方向移动，到窗口边缘停下来而不是穿出去。

判断标准：每按一次方向键，鱼的位置沿对应方向移动；按住不放可以持续移动；同时按两个方向键时，鱼应该沿斜线运动。如果不能移动，先点击窗口标题栏确保窗口获得焦点，再按方向键。Pygame 的键盘状态读取依赖窗口焦点，这是最容易忽略的问题之一。

5.3 食物与成长测试

把鱼移动到食物附近，确认两者靠近后食物消失、分数 +1、鱼的身体半径变大。

判断标准：分数只增不减，食物被吃掉后会重新生成，鱼的最大半径不超过 120。如果鱼穿过食物但没有触发碰撞，检查eat()中的距离公式是不是写成了加法，或者食物半径food[2]取值过小。如果食物一直不补充，检查spawn_food(5)触发条件是否在暂停状态下被跳过。

5.4 暂停与退出测试

按空格键，左上角显示paused: True，鱼和食物都不再运动。再按空格，恢复运动。按 ESC 或关闭窗口，进程正常结束。

判断标准：暂停期间帧率仍在刷新，但游戏逻辑不更新；退出后终端回到命令行，没有残留 Python 进程。如果按空格没反应，检查事件循环里是否对pygame.K_SPACE做了处理。如果退出后终端卡住，检查是否调用了pygame.quit()和sys.exit(0)。

5.5 功能测试清单

6. 接口 API 与批量任务

大肥鱼最有工程价值的部分在这里：一个独立的 API 服务控制运行参数，一个无窗口批量渲染脚本。这两块让“本地程序 + 外部控制 + 自动产出”的链路完全跑通。

6.1 接口 API 启动方式

api_server.py 是一个基于 Python 标准库 HTTP 服务的独立进程，不依赖 Flask、Django。它启动后监听127.0.0.1:8900，提供两个端点：

• GET /status：返回 JSON 格式的服务状态信息。
• POST /control：接收 JSON，将参数合并写入 control.json。

# api_server.py import json import os from http.server import BaseHTTPRequestHandler, HTTPServer CONTROL_FILE = "control.json" HOST = "127.0.0.1" PORT = 8900 class Handler(BaseHTTPRequestHandler): def do_GET(self): if self.path == "/status": body = json.dumps({"service": "bigfish", "pid": os.getpid()}).encode() self.send_response(200) self.send_header("Content-Type", "application/json; charset=utf-8") self.send_header("Content-Length", str(len(body))) self.end_headers() self.wfile.write(body) else: self.send_response(404) self.end_headers() def do_POST(self): if self.path == "/control": try: length = int(self.headers.get("Content-Length", 0)) data = json.loads(self.rfile.read(length)) current = {} if os.path.exists(CONTROL_FILE): with open(CONTROL_FILE, "r", encoding="utf-8") as f: current = json.load(f) current.update(data) with open(CONTROL_FILE, "w", encoding="utf-8") as f: json.dump(current, f, ensure_ascii=False, indent=2) body = json.dumps({"ok": True}).encode() self.send_response(200) self.send_header("Content-Type", "application/json; charset=utf-8") self.send_header("Content-Length", str(len(body))) self.end_headers() self.wfile.write(body) except Exception as e: body = json.dumps({"ok": False, "error": str(e)}).encode() self.send_response(400) self.send_header("Content-Type", "application/json; charset=utf-8") self.send_header("Content-Length", str(len(body))) self.end_headers() self.wfile.write(body) else: self.send_response(404) self.end_headers() def log_message(self, *args): pass if __name__ == "__main__": server = HTTPServer((HOST, PORT), Handler) print(f"BigFish API: http://{HOST}:{PORT}") server.serve_forever()

保存后启动：

python api_server.py

注意，API 服务和 main.py 是两个独立进程。先启动 API，再启动 main.py，或者反过来都行，因为 main.py 每次刷新时会读取最新的 control.json。如果你只启动 API 不启动主程序，也能正常收到响应，文件会被写入，但看不到游戏画面变化。

6.2 接口调用示例

先用 curl 查看状态：

curl http://127.0.0.1:8900/status

正常返回：

{"service": "bigfish", "pid": 12345}

再通过接口调整速度和食物数量：

curl -X POST http://127.0.0.1:8900/control \ -H "Content-Type: application/json" \ -d '{"speed": 8, "food_count": 20}'

如果写入成功，API 返回{"ok": true}。此时 main.py 会在下一帧读取 control.json，并应用新的速度和食物补充数量。用 Python 调用也是同样的逻辑：

import requests url = "http://127.0.0.1:8900/control" payload = {"speed": 8, "food_count": 20} response = requests.post(url, json=payload, timeout=5) print(response.json())

这里用到了 requests 库，如果本地没有安装，可以执行pip install requests。当然，直接用标准库 urllib 也可以，示例略。

控制点可以继续扩展。比如在 control.json 里加bg_color，让主程序读取后改变背景色；加fish_color，改变鱼身 RGB。大肥鱼的接口设计不复杂，但足够演示配置下发的完整链路。

6.3 批量截图任务

批量渲染是另一个实用功能。在本地开发中，你可能需要快速生成一批小鱼在不同位置的 PNG 素材，用于文档配图或算法测试。如果不做特殊处理，Pygame 会弹出一个窗口，影响自动化脚本运行。解决办法是设置SDL_VIDEODRIVER=dummy，让 Pygame 不创建可见窗口，直接在内存中渲染。

# batch_screenshot.py import os import random import pygame # 无窗口模式渲染，适合批量任务 os.environ["SDL_VIDEODRIVER"] = "dummy" pygame.init() WIDTH, HEIGHT = 800, 600 screen = pygame.display.set_mode((WIDTH, HEIGHT)) os.makedirs("shots", exist_ok=True) for idx in range(30): # 绘制背景 screen.fill((20, 30, 48)) # 在随机位置绘制鱼身 body_x = random.randint(100, 600) body_y = random.randint(100, 400) pygame.draw.ellipse(screen, (70, 140, 220), (body_x, body_y, 200, 120)) # 绘制一个随机食物 food_x = random.randint(50, 750) food_y = random.randint(50, 550) pygame.draw.circle(screen, (255, 210, 90), (food_x, food_y), 15) # 保存当前帧 pygame.image.save(screen, f"shots/frame_{idx:03d}.png") pygame.quit() print("batch screenshot done")

运行：

python batch_screenshot.py

程序执行后会在当前目录生成 shots 文件夹，里面是 30 张无窗口模式渲染出的 PNG 截图。这个过程没有弹窗，适合放进定时任务或 CI 流程。

批量任务真正落地时要注意三点。第一，确保 shots 目录存在，否则保存会报错。第二，如果你需要固定种子复现同一批图，可以在循环外设置random.seed(42)。第三，如果目标生成量很大，建议分批执行，并在每次执行后检查输出文件数量，防止中途异常中断。

7. 资源占用与性能观察

大肥鱼是纯 CPU 渲染项目，不调用 GPU，所以重点观察的是 CPU 和内存。

在 Windows 上运行时，打开任务管理器，在“进程”标签里找到 python.exe，观察 CPU 和内存占用。在 Linux 上可以用top或htop：

top -p $(pgrep -f main.py)

需要明确一点：本文不给出固定数字，因为实际占用会受 Python 版本、Pygame 依赖版本、窗口分辨率、操作系统驱动等因素影响。更稳妥的做法是跑起来后自己观察基线值，然后修改参数做对比实验。

影响资源占用的主要因素有三个。

第一是帧率。clock.tick(60)会把刷新率限制在 60 FPS 左右。如果你把参数改成 120，CPU 占用会明显更高，因为每秒钟要渲染两倍的帧。对大肥鱼这种画面不复杂的项目，60 FPS 已经足够。如果只想看动画效果不想追求流畅度，改成 30 FPS 会进一步降低 CPU 占用。

第二是窗口分辨率。默认 800x600 的窗口比较保守。如果你改成 1920x1080，每个像素都要参与填充和绘制，CPU 占用会上一个台阶。降低分辨率是最直接的减负方式。

第三是食物数量和鱼身体绘制复杂度。食物数量从 10 增加到 100，遍历碰撞检测的次数会变多，CPU 占用自然上升。鱼身体的绘制只有三个形状，开销很小，但如果后续换成贴图，还要考虑贴图解码和缩放的开销。

在 Linux 或容器里跑批量截图时，因为SDL_VIDEODRIVER=dummy完全不创建窗口，画面不输出到真实显示器，整体资源占用会比交互模式低不少。这也是批量任务脚本适合放到后台跑的原因。

还有一个容易被忽略的问题：进程残留。如果 main.py 没有正常调用pygame.quit()就被强制终止，Pygame 的窗口可能来不及销毁，CPU 占用可能不会立刻归零。遇到这种情况，在任务管理器里找到对应的 python 进程手动结束即可。批量截图脚本如果跑完后没有退出，检查循环内是否使用了pygame.quit()，以及是否存在无限循环。

8. 常见问题与排查方法

大肥鱼项目代码量不大，但运行环境五花八门，最常见的坑集中在依赖安装、窗口焦点、端口占用和路径问题。下面整理成一张排查表。

端口冲突是一个值得重点说的情况。默认 API 端口是 8900，如果本机已有程序占用，API 服务会直接启动失败，报Address already in use。最简单的处理方式是换一个端口，比如改成 8910：

PORT = 8910

然后重新启动 API 服务。因为 main.py 只读取 control.json，不关心 API 端口，所以端口可以随便改。

另一个容易踩的坑是运行目录不一致。如果你在项目目录外执行python /path/to/main.py，main.py 里的open("control.json")会去当前工作目录找文件，而不是去 main.py 所在目录。这会造成“接口明明返回成功，但游戏没变化”的假象。更稳妥的做法是，先cd到项目目录，再执行脚本。

9. 最佳实践与使用建议

大肥鱼是一个可以继续扩展的实验项目，但在扩展之前，先把工程习惯养好。

第一，代码模块拆分。现在 main.py 里同时包含窗口初始化、鱼对象、食物生成和主循环。功能少的时候没问题，如果后续要加音效、加贴图、加多种敌人，建议拆成render.py、logic.py、config.py三个模块。这样每个文件只做一件事，调试成本会低很多。

第二，配置集中管理。speed 和 food_count 已经支持通过 control.json 下发，但更规范的做法是准备一个default_config.json，每次启动时先加载默认配置，再合并 control.json。这样即使 control.json 被误删，程序也有合理的默认值兜底。

第三，日志留痕。API 服务目前没有打印请求日志，这在联调阶段不方便。建议在每个接口处理函数里加一行标准输出，记录时间、请求路径和响应状态码。如果再想做得细致一点，可以输出到api.log。

import datetime def log(msg): print(f"[{datetime.datetime.now()}] {msg}")

第四，接口安全。大肥鱼的 API 只绑定了 127.0.0.1，这是正确的默认选择。如果你确实需要在局域网内测试，可以把 HOST 改成0.0.0.0，但这意味着任何能访问到该端口的人都可能修改配置文件。建议在接口里加一个简单的 token 参数，暂时不做复杂鉴权，至少挡住误操作。

第五，素材版权。如果你要给大肥鱼换皮肤、换背景音乐、加音效，优先使用自己绘制或明确允许免费商用的素材。不要直接解包商业游戏素材用于发布或公开分享，这涉及版权风险。

第六，已经买了新显卡、新电脑的人，不需要为这个项目升级硬件。它不跑模型，不看 CUDA，不占显存，一台能跑 Python 的旧电脑完全够用。真正值得多花时间的不是硬件，而是把接口服务、批量渲染、配置管理这套本地自动化流程吃透。

10. 总结与下一步

大肥鱼最值得尝试的点是它的完整性。从窗口渲染到碰撞检测，从 HTTP 接口到无窗口批量截图，一个迷你项目把本地工具开发中常见的多个环节都走了一遍。你不需要对着文档啃大框架，只需要跑起一份几百行代码就能看懂全貌的项目，这是它最大的优势。

建议你第一次运行后，先验证最基本的启动和键盘移动，再把 API 服务跑起来，用 curl 或 Python 请求修改食物数量，观察游戏变化。紧接着运行批量截图脚本，确认无窗口模式是否生成图片。这三步跑通，基本就掌握了这个项目的核心链路。

最容易踩的坑是 Pygame 依赖安装失败和窗口焦点问题。前者可以通过升级 Python 版本或使用国内镜像解决，后者只需要鼠标点击窗口即可。API 相关的坑则集中在端口占用和运行目录不一致，排查时优先看这两点。

后续扩展方向很明确：可以给鱼加不同贴图，实现“换肤”效果；可以加背景音乐和音效，改进反馈体验；可以把渲染结果推送到本地 Web 页面，变成浏览器可访问的小动画；可以在 API 里增加更多控制参数，比如鱼的颜色、背景颜色、食物大小。如果你对游戏开发或桌面工具开发感兴趣，大肥鱼是一个很好的起步点。