纯小白必看：如何正确提交 Issue与常见技术黑话解释

纯小白必看：如何正确提交 Issue 与常见技术黑话解释
很多刚接触服务器、建站、开源项目的新手，都会遇到同一个问题：

问题明明存在，但 Issue 提交了却没人回复。
这并不是你运气不好，也不是项目“没人维护”，而是你提供的信息不足，别人无法帮你判断问题。
这篇文章是专门写给纯小白的，不假设你有任何技术基础，手把手告诉你：
一个「别人愿意看」的 Issue 应该怎么写
截图到底该截什么，为什么你之前的截图没用
日志是什么，为什么别人总让你“看日志”
技术群、Issue 里常见的“黑话”到底什么意思

一、先说清楚一件事：Issue 不是“求助帖”
在开源社区里：

Issue = 问题报告，而不是求救信息
下面这些写法，几乎一定没人回：
❌「大佬，项目跑不起来」
❌「访问就是 502」
❌「有没有人遇到过？」
❌ 只发一张白屏截图
因为维护者不知道你在用什么、做了什么、哪里出了问题。

二、一个“合格 Issue”最少要包含什么？
你可以把 Issue 当成一份：

“我已经把问题尽量查清楚了，现在需要你帮我确认”的说明书
下面这些内容，缺一个，解决难度就翻倍。

三、提交 Issue 前必须准备的内容（照着做）
3.1 基本环境信息（必填）
请直接写清楚：
你用的是什么系统
Windows / macOS / Linux
项目或程序版本
你是怎么运行它的
示例（照抄格式即可）：
系统：Ubuntu24
项目版本：v1.2.3
运行方式：docker-compose

3.2 问题现象描述（不要一句话）
请回答下面四个问题：

1. 你做了什么？
2. 你访问了什么？
3. 实际发生了什么？
4. 你本来以为会发生什么？
   示例：
   我访问 https://example.com
   页面无法打开
   浏览器显示 502 Bad Gateway
   我预期应该正常显示首页

四、重点：小白最容易犯错的——截图问题（非常重要）
4.1 先记住一句话

截图不是“证明我有问题”，而是“让别人通过截图分析问题”。

4.2 新手最常见的错误截图
下面这些截图，基本等于没提供信息：
❌ 只截一个“502 / 403”页面
❌ 只截白屏
❌ 截图裁剪太狠，看不到上下文
❌ 手机拍屏幕，模糊、有反光
❌ 截图里没有任何文字

4.3 正确的截图方式（照着来）
4.3.1 浏览器打不开 / 白屏 / 报错
必须截图以下至少一个：
浏览器 Console（控制台）
浏览器 Network（网络请求）
截图时请保证：
能看到 报错文字
能看到 请求地址
能看到 状态码
📌 提示：
Chrome / Edge 按 F12 → Console / Network

4.3.2 出现 502 / 504 / 403
截图必须包含：
完整访问地址（不要只截中间）
错误码
返回内容
❌ 只截一个“502 Bad Gateway”大字是完全没用的。

4.3.3 程序启动失败
截图或粘贴：
启动命令
完整报错信息
报错前后几行内容
❌ 不要只截最后一句“启动失败”。

4.4 截图 vs 文本，怎么选？
原则只有一个：

能复制的内容，一定要用文本，不要截图。
推荐：
报错信息 → 文本
日志 → 文本
页面异常 → 截图辅助

4.5 一张“合格截图”的判断标准
你可以问自己一句话：

如果我把这张截图发给别人，他能不能只靠这张图判断问题方向？
如果不能，那这张截图就不合格。

五、日志是什么？为什么别人一直让你“看日志”？
5.1 什么是日志？
日志就是程序在运行时留下的“自述书”，
它会告诉你：
程序有没有启动
哪里报错了
错误原因是什么

5.2 常见必须提供的日志
5.2.1 Docker 项目
docker logs 容器名
5.2.2 Nginx 日志
error.log（一定要）
access.log（必要时）
示例：
connect() failed (111: Connection refused)

六、配置文件（记得脱敏）
如果问题和配置有关，请提供配置文件：
nginx.conf
docker-compose.yml
.env
⚠️ 一定要删除：
密码
Token
Secret
可以统一替换为：
xxxxxx

七、推荐的 Issue 标准模板（直接用）
【系统环境】
系统：
项目版本：
运行方式：
【问题描述】
我做了什么：
发生了什么：
预期结果：
【报错信息】
（完整文本）
【相关日志】
（docker / nginx 日志）
【相关截图】
（包含关键部分）
【已尝试的解决方法】

八、常见技术黑话（纯小白版）
8.1 A 到 / 4A 到 / C 到
A 到：域名指向 IPv4 地址
4A 到（AAAA）：域名指向 IPv6
C 到：域名指向另一个域名（常见于 CDN）

8.2 源站 / 回源
源站：真正的服务器
回源：CDN 找服务器拿数据

8.3 裸奔
网站没有 CDN、防护
IP 直接暴露

8.4 502 / 504
502：后端服务有问题
504：后端响应太慢

8.5 端口没放行
云厂商安全组没开
防火墙拦截

九、最后想说的话

会正确提交 Issue，本身就是技术能力。
当你学会：
提供完整信息
截有用的截图
粘贴关键日志
你会发现：
别人更愿意帮你
问题解决得更快
自己也进步得更快