企业官网建设流程全解析

1. 为什么用 Flask 套一个俄罗斯方块？

先聊聊这个组合的初衷。俄罗斯方块这种经典游戏，纯前端用 HTML + JavaScript 半小时就能跑起来，为什么非要绑一个 Flask 后端？我当时的场景是：需要一个既能演示游戏本身，又能给前端初学者展示"前后端到底怎么配合"的完整项目。如果只写一个静态网页，F12 打开网络面板一片空白，新手永远不知道 HTTP 请求长什么样。而搭一个 Flask 服务后，游戏逻辑在前端跑，分数上报、排行榜、存档这些数据交互走后端接口，整个 Web 应用的闭环就出来了。

另外一个现实原因是部署和演示环境。用 Flask 时，一个app.py就能把静态文件托管、API 接口、模板渲染全包了，不需要单独配 Nginx 或 Node 服务。对于只想在局域网内展示项目、或者作为课程设计交作业的场景，这个方案最省事——对方只需要装 Python，pip install flask后一条命令就能看到游戏界面，不用折腾任何前端脚手架。

这个项目解决的典型问题包括：

• 用 Flask 提供静态页面和 API 接口，演示一个完整 Web 应用的请求-响应链路
• 用一个可玩性完整的俄罗斯方块实现游戏核心逻辑（方块旋转、碰撞检测、消行计分）
• 通过 localStorage 做本地存档，通过 Flask 接口做简单的排行榜服务
• 给不太熟悉 Web 架构的人一个能跑通的参考模板

适合谁来参考？如果你是刚学 Flask 想找个练手项目，或者正在带学生做 Web 入门、需要一个不太复杂但五脏俱全的示例，这篇内容可以直接作为脚手架。我下面会把设计思路、核心代码、踩过的坑全部拆开讲。

2. 整体设计方案：前端逻辑 + 后端薄壳

2.1 为什么游戏逻辑放在前端而不是后端

这是最容易被问的问题。俄罗斯方块的游戏循环（下落、移动、旋转、消行）需要每帧更新界面，如果放到后端做，意味着每个操作都要发一次 HTTP 请求，延迟根本扛不住。实测里，局域网环境下请求耗时约 5-15ms，加上 JSON 序列化和渲染，一帧 16ms 的游戏循环会直接被拖垮。网络抖动一次，方块就卡到下一格了。

所以正确的架构是：游戏引擎跑在浏览器里，Flask 只做三件事：

1. 托管静态文件（HTML/CSS/JS）
2. 提供 API 接口处理分数上报和排行榜
3. 用模板渲染实现简单的页面切换（比如首页、关于页）

这样做还有一个额外好处：游戏主逻辑不依赖网络，关掉后端也能玩（除了排行榜功能），可以清晰地区分出"纯前端能力"和"前后端协作"的边界。我在写这个项目时，特意把游戏核心逻辑放在static/js/tetris.js里，app.py只留路由和 API，前端同学单独打开 JS 文件也能读懂全部游戏流程。

2.2 技术选型对照

先列一个对比表，方便你判断这套方案和别的游戏开发模式的差异：

从课程设计和入门教学的角度，Flask + 原生 JS 是我测试下来性价比最高的路线：部署门槛最低，代码量适中，同时能覆盖"前端交互 + 后端接口 + 数据存储"三个教学点。

2.3 项目目录和文件规划

我按下面这个结构组织文件，职责非常明确：

tetris-flask/ ├── app.py # Flask 主程序，路由和 API ├── requirements.txt # 依赖列表 ├── templates/ │ ├── index.html # 游戏主页面 │ ├── leaderboard.html # 排行榜页面 │ └── about.html # 关于页面 └── static/ ├── css/ │ └── style.css # 页面样式 └── js/ ├── tetris.js # 游戏核心逻辑 └── api.js # 与后端交互的封装

text

在这个结构里，templates是 Flask 默认的模板目录，static是静态资源目录，用url_for('static', filename='...')可以自动解析路径，不会出现相对路径 404 的问题。

3. 核心实现细节：从零开始写俄罗斯方块逻辑

3.1 棋盘与方块的表示方法

俄罗斯方块的棋盘是 10 列 × 20 行，我用一个二维数组表示：board[row][col]，值为 0 表示空，值为非 0 表示有方块。为什么不用一维数组？因为二维数组更直观，消行时直接splice行数据后再头部插入新行，代码可读性和维护性都好很多。

每种方块用一个 4×4 矩阵表示，旋转就是矩阵转置加行反转，这个操作非常经典。我用一个对象存储所有方块形状：

const SHAPES = { I: [[0,0,0,0],[1,1,1,1],[0,0,0,0],[0,0,0,0]], O: [[1,1],[1,1]], T: [[0,1,0],[1,1,1],[0,0,0]], S: [[0,1,1],[1,1,0],[0,0,0]], Z: [[1,1,0],[0,1,1],[0,0,0]], J: [[1,0,0],[1,1,1],[0,0,0]], L: [[0,0,1],[1,1,1],[0,0,0]], };

3.2 碰撞检测的思路

碰撞检测是整个游戏最核心的算法。每个方块在移动或旋转之前，先把目标位置的所有格子临时写入棋盘，检查是否越界或与已有格子重叠。

我在tetris.js里写了一个collision(board, shape, offset)函数：

function collision(board, shape, offset) { for (let r = 0; r < shape.length; r++) { for (let c = 0; c < shape[0].length; c++) { if (shape[r][c] !== 0) { const boardRow = offset.row + r; const boardCol = offset.col + c; if (boardRow < 0 || boardRow >= board.length || boardCol < 0 || boardCol >= board[0].length || board[boardRow][boardCol] !== 0) { return true; } } } } return false; }

注意判断顺序：先判越界再判占用。先越界判断能避免数组下标访问报错，这是很多新手最容易漏掉的边界条件。比如board[-1]是 undefined，再访问board[-1][c]就直接抛异常了。

3.3 旋转逻辑与墙踢

旋转是俄罗斯方块里最常见的坑。如果只是简单转置矩阵，在靠近墙边时一定会出现"转完就出界"或者"转完和已有方块重叠"的情况。业界通用的解决方案是墙踢（Wall Kick）：旋转后如果发生碰撞，就把方块往左或右平移，尝试 1-2 格，找到一个合法位置。

我实现了一个精简版墙踢：

function rotate(matrix) { const N = matrix.length; const rotated = []; for (let i = 0; i < N; i++) { rotated[i] = []; for (let j = 0; j < N; j++) { rotated[i][j] = matrix[N - 1 - j][i]; } } return rotated; } function tryRotate(board, current) { const rotated = rotate(current.shape); const kicks = [0, -1, 1, -2, 2]; for (const offset of kicks) { const newOffset = { row: current.row, col: current.col + offset }; if (!collision(board, rotated, newOffset)) { current.shape = rotated; current.col += offset; return true; } } return false; }

kicks数组的含义：先尝试原地旋转，不行就往左一格，再往右一格，再向左两格，再向右两格。实测下来，用这个 5 步墙踢策略覆盖了 95% 的异形旋转场景。真正的《俄罗斯方块》官方还区分 J/L/S/T/Z 方块有不同的踢墙表，但这里用通用偏移已经足够顺手。

3.4 消行与分数计算

当一行被填满时，将该行从数组中删除，并在顶部插入一个空行。这个过程的核心是逆序遍历，因为从上往下删除会改变行索引。

function clearRows(board) { let rowsCleared = 0; for (let row = board.length - 1; row >= 0; ) { if (board[row].every(cell => cell !== 0)) { board.splice(row, 1); board.unshift(new Array(COLS).fill(0)); rowsCleared++; // 不增加 row，因为上面的行已经下降了，重新检查当前索引 } else { row--; } } return rowsCleared; }

计分我参考了常见的规则：消 1 行得 100 分，2 行得 300 分，3 行得 500 分，4 行得 800 分。累计消除行数超过 10 行时提高一个大关，下落速度setTimeout间隔从 500ms 递减到 100ms，递减步长是 20ms。

3.5 游戏主循环的写法

我没有用setInterval而是用setTimeout递归来实现下落。这样做的好处是：每帧之间的间隔可以动态调整（比如按加速按钮时立刻生效），而且固定间隔的setInterval在浏览器标签页切走再回来时会积压大量回调，导致方块瞬间掉到底部。setTimeout递归则天然规避了这个问题。

function gameLoop() { if (!gameOver) { drop(); draw(); speed = Math.max(100, 500 - level * 30); timer = setTimeout(gameLoop, speed); } }

4. Flask 后端：路由、API 与模板渲染

4.1 Flask 应用骨架

以下是我app.py的核心代码，注释标清楚了每个路由的职责：

from flask import Flask, render_template, request, jsonify import sqlite3 import os app = Flask(__name__) DB_PATH = os.path.join(os.path.dirname(__file__), "scores.db") def init_db(): conn = sqlite3.connect(DB_PATH) c = conn.cursor() c.execute('''CREATE TABLE IF NOT EXISTS scores (id INTEGER PRIMARY KEY AUTOINCREMENT, player_name TEXT NOT NULL, score INTEGER NOT NULL, lines INTEGER, level INTEGER, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP)''') conn.commit() conn.close()

因为两个路由都要用数据库，我把它提取成一个独立的函数，避免在不同函数里重复sqlite3.connect。

4.2 路由设计与请求处理

首页和排行榜页用render_template渲染模板：

@app.route("/") def index(): return render_template("index.html") @app.route("/leaderboard") def leaderboard(): conn = sqlite3.connect(DB_PATH) c = conn.cursor() c.execute("SELECT player_name, score, lines, level, created_at FROM scores ORDER BY score DESC LIMIT 10") rows = c.fetchall() conn.close() return render_template("leaderboard.html", scores=rows)

提交分数走 POST 接口：

@app.route("/api/score", methods=["POST"]) def save_score(): data = request.get_json() player_name = data.get("playerName", "Anonymous") score = data.get("score", 0) lines = data.get("lines", 0) level = data.get("level", 1) if not player_name.strip(): player_name = "Anonymous" conn = sqlite3.connect(DB_PATH) c = conn.cursor() c.execute("INSERT INTO scores (player_name, score, lines, level) VALUES (?, ?, ?, ?)", (player_name, score, lines, level)) conn.commit() last_id = c.lastrowid conn.close() return jsonify({"status": "ok", "id": last_id})

一个细节：POST 接口参数类型处理。前端传过来的score可能是字符串，所以我在后端做了一次int()转换并用默认值兜底。data.get("score", 0)在 JSON 里字段缺失或为 null 时都会用默认值 0，比直接data["score"]安全得多。

4.3 模板渲染与静态资源路径

Flask 的模板引擎是 Jinja2，在leaderboard.html里直接循环渲染数据：

<table> <thead> <tr><th>排名</th><th>玩家</th><th>分数</th><th>行数</th><th>级别</th><th>时间</th></tr> </thead> <tbody> {% for score in scores %} <tr> <td>{{ loop.index }}</td> <td>{{ score[1] }}</td> <td>{{ score[2] }}</td> <td>{{ score[3] }}</td> <td>{{ score[4] }}</td> <td>{{ score[5] }}</td> </tr> {% endfor %} </tbody> </table>

score是一个元组（因为fetchall()返回的就是元组列表），所以用下标访问。如果你更习惯字典，可以在查询时加row_factory = sqlite3.Row，这样就能用score["player_name"]来访问，代码会更可读。

4.4 前端请求后端的两种方式

在api.js里，我封装了几个接口调用函数，示例如下：

async function submitScore(name, score, lines, level) { const response = await fetch("/api/score", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ playerName: name, score: score, lines: lines, level: level }) }); return await response.json(); }

这里必须设置Content-Type: application/json，否则 Flask 的request.get_json()会返回None。我见过不少新手在这里卡住，表现为前端 console 显示请求成功，但数据库里没有新记录——因为请求体是空的或格式不对，后端拿到的是None然后报了 500。

5. 实操过程：从零搭建并跑通的完整记录

5.1 环境准备

我用的 Python 版本是 3.10，Flask 版本是 3.0.x。先创建虚拟环境再安装依赖：

python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate pip install flask

提示：项目规模不大时，requirements.txt里只需要写flask一行就够了。如果后续要加数据库迁移、错误追踪，再逐步引入flask-sqlalchemy、flask-migrate等库。

5.2 前端页面的骨架

index.html的核心结构是左侧游戏画布 + 右侧信息栏。游戏画布我用<canvas>而不是 DOM 格子，原因很简单：canvas 的渲染性能远高于几十个 DOM 节点的频繁操作。一帧 10×20 的方格，canvas 绘制只需一次fillRect循环，而如果用 DOM 的话，每次更新方块位置都要操作 200 个节点的 class 属性，浏览器重排的成本会明显拖慢游戏。

页面骨架：

<!doctype html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>俄罗斯方块 - Flask Edition</title> <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}"> </head> <body> <div class="game-container"> <canvas id="board-canvas" width="300" height="600"></canvas> <div class="side-panel"> <div>分数: <span id="score">0</span></div> <div>行数: <span id="lines">0</span></div> <div>级别: <span id="level">1</span></div> <button id="pause-btn">暂停</button> <button id="restart-btn">重新开始</button> <input type="text" id="player-name" placeholder="输入名字"> <button id="save-score-btn">保存分数</button> <a href="/leaderboard">查看排行</a> </div> </div> <script src="{{ url_for('static', filename='js/tetris.js') }}"></script> <script src="{{ url_for('static', filename='js/api.js') }}"></script> <script src="{{ url_for('static', filename='js/main.js') }}"></script> </body> </html>

5.3 前端 JS 框架约定

因为这是一个教学向项目，我没有用任何前端框架，直接用三个 JS 文件分工：

• tetris.js：纯游戏逻辑，暴露Tetris全局对象
• api.js：所有fetch调用，负责和后端交互
• main.js：初始化游戏，绑定页面事件

main.js里的核心初始化代码：

const game = new Tetris(); const canvas = document.getElementById("board-canvas"); const ctx = canvas.getContext("2d"); document.addEventListener("keydown", (e) => { if (e.key === "ArrowLeft") game.moveLeft(); if (e.key === "ArrowRight") game.moveRight(); if (e.key === "ArrowDown") game.moveDown(); if (e.key === "ArrowUp") game.tryRotate(); if (e.key === " ") { e.preventDefault(); game.hardDrop(); } if (e.key === "p") game.togglePause(); }); function draw() { ctx.clearRect(0, 0, canvas.width, canvas.height); game.drawBoard(ctx); game.drawCurrentPiece(ctx); game.drawGhost(ctx); document.getElementById("score").textContent = game.score; document.getElementById("lines").textContent = game.lines; document.getElementById("level").textContent = game.level; }

5.4 运行与测试

启动服务：

python app.py # 默认端口 5000，浏览器打开 http://127.0.0.1:5000

功能测试清单：

1. 方向键控制方块移动旋转，空格键硬降，P 键暂停
2. 填满一行自动消除，分数正确累计
3. 游戏结束后弹出"是否保存分数"提示
4. 提交分数后跳转到排行榜页面，刷新后数据仍在
5. localStorage 里保存的"最高分"能跨页面读取

6. 常见问题与排查技巧实录

6.1 方块旋转后"穿模"或"瞬移"

这是最典型的俄罗斯方块开发问题。多数情况是碰撞检测没有考虑旋转后实际写入棋盘的位置。我排查时习惯在tryRotate的每个kicks偏移后打印当前方块和棋盘状态，肉眼比对很容易发现到底是哪里多算了一格。

如果旋转后方块到了不该去的位置，优先检查矩阵转置方向是否正确。顺时针旋转代码是rotated[i][j] = matrix[N-1-j][i]，逆时针是rotated[i][j] = matrix[j][N-1-i]，方向搞反会出现左右镜像翻转。

6.2 Flask 静态资源 404

使用url_for('static', filename='js/tetris.js')可以避免硬编码路径问题，但如果你直接写static/js/tetris.js，在部分路由前缀下会失效。在模板里调试 404 时，先按 F12 打开 Network 面板看请求的完整 URL，确认是路径拼接问题还是文件缺失。

6.3 排行榜数据显示乱码

中文显示乱码，几乎都是数据库编码问题。我建库时统一指定 UTF-8：

conn = sqlite3.connect(DB_PATH) conn.execute("PRAGMA encoding = 'UTF-8'")

Flask 的 JSON 响应默认就是 UTF-8，理论上不会有问题，但 Python 文件和 HTML 模板本身的编码必须是 UTF-8。在app.py文件头部声明# -*- coding: utf-8 -*-（Python 3 默认 UTF-8，其实不用加，但如果编辑器配置混乱，加了更保险）。

6.4 页面刷新后分数丢失

这是设计问题，不是 bug。我的方案是游戏进行中把最高分实时写入 localStorage：

function saveLocalHighScore(score) { const high = localStorage.getItem("tetris_high_score") || 0; if (score > high) { localStorage.setItem("tetris_high_score", score); } }

这个函数在每次消行后调用，这样即使中途关了标签页，最高分也还在。每次开始新游戏时，从 localStorage 读取并显示在界面上。

6.5 常见问题速查表

7. 更进一步：还能怎么扩展这个项目

做完一个基本可玩的版本后，我为了增加教学深度，把存档和历史记录也做了，但没有让项目膨胀到难以维护的程度。这里分享一下可以继续扩展的方向，按优先级排序：

1. 加入积分和游戏状态的后台持久化：当前的排行榜只保存了每次的结果，但如果要支持"继续游戏"功能，可以把棋盘状态和当前方块序列化后存入数据库，下次打开时反序列化恢复。

2. 增加"下一个方块预览"：在游戏逻辑里维护一个队列，显示下一个要出现的方块，算是俄罗斯方块的标准体验优化，难度不大但非常提升质感。

3. 用 WebSocket 做双人对战：把双方的游戏事件传到一个房间，实现实时对战。考虑到 Flask 生态，可以用 Flask-SocketIO 来做，但安装依赖会多一些。

4. 移动端触控支持：加几个按钮或监听触摸滑动事件，注意在触屏上按方向键本来就不方便，属于加分项。

不过我要特别提醒一点：不要一上来就上 React/Vue。这个项目最大的价值就是让初学者理解"原生 JS + 后端接口"的底层链路。一旦引入前端框架，虽然代码组织更工程化，但学习曲线和项目体积都会立刻变大。把这个 Flask 版的俄罗斯方块跑通、读懂、改熟之后，再去谈框架才水到渠成。

8. 最后补充的两个小技巧

写这个项目时有个小经验让我印象很深——游戏的硬降（Hard Drop）功能一定要做，不然键盘按方向键一下一下下落太折磨人。实现其实很简单：将当前方块直接下落到碰撞位置，然后把这次下落经过的所有行格数计入额外得分。这个操作对游戏体验的提升非常明显，建议后续加功能优先做它。

还有一个细节是关于 canvas 绘制的：每帧重绘时，方块颜色可以用 HSL 色相值循环，比如hsl(${30 * typeIndex}, 70%, 60%)，视觉效果比固定的七种颜色鲜艳很多，代码量只多两行。这种小优化适合在给朋友演示项目时用来拉高印象分。

俄罗斯方块这个项目做完，我的体会是：它把 Flask 的模板、路由、POST 接口、SQLite 读写，以及前端的 canvas、请求、事件处理、游戏循环全部串起来了。对 Web 开发新手来说，这比单独看 Flask 文档里那些 hello world 例子有用得多。你可以先照着上面的代码跑通，然后尝试改改参数——比如把棋盘加大到 12×22、改变消行得分、增加方块新种类，改完你就会发现，这个项目看起来简单，但每一块都是可以继续玩下去的内容。