如何撰寫開發者能修復的錯誤報告，並用 Mac 快捷鍵加快整理

A bad bug report costs more time than the bug. "It's broken on my machine" turns into three rounds of "what version?", "can you send a screenshot?", and "what did you click first?" before anyone even opens the code. A good report answers those questions up front, and on a Mac, almost everything you need to collect is one shortcut or one command away. Here's the checklist I use, whether I'm filing an issue on someone's open source project or writing one up for my own team.

1. Write the title as "what happened, where"

The title is what a maintainer sees in a list of 200 open issues. Make it specific enough to triage without clicking.

• Bad: App crashes
• Bad: URGENT!!! export broken
• Good: Crash when exporting a PDF with an empty title field (v2.3.1, macOS 15)

A useful pattern: action + symptom + condition. "Saving a file over SMB hangs for 30s when the share is offline" tells the reader what you were doing, what went wrong, and the condition that seems to matter.

2. Steps to reproduce: numbered, minimal, from a clean start

This is the section that decides whether your bug gets fixed. Write steps someone else can follow without guessing:

1. Start from a fresh state (new project, logged out, default settings, whatever "clean" means for this app).
2. Number every step, one action per line.
3. Include the exact input you used. If you typed something, paste it. If you opened a file, attach it or describe how to make one.
4. Then cut it down. Remove each step and check whether the bug still happens. The shortest list that still reproduces the bug is worth far more than the full story of your afternoon.

If you can't reproduce it reliably, say so and say how often: "about 1 in 5 tries" is useful information, not an admission of failure.

3. Expected vs actual, as two separate lines

Don't make the reader infer what you thought should happen.

Expected: The PDF exports with "Untitled" as the document title.
Actual: The app quits immediately. No error dialog.

Two lines. It forces you to notice when the "bug" is really a disagreement about intended behavior, which is a different (and often faster) conversation.

4. Grab your environment details in one command

Version numbers are the most commonly missing piece of a bug report. On a Mac you can get the OS details in one go:

sw_vers

That prints the product name, version, and build. For the chip and memory, add:

sysctl -n machdep.cpu.brand_string
system_profiler SPHardwareDataType | grep -E "Chip|Memory"

Pipe any of it straight to your clipboard so you never retype version numbers by hand:

{ sw_vers; sysctl -n machdep.cpu.brand_string; } | pbcopy

Then add the app's own version (usually in its About window) and, for CLI tools, the output of tool --version. For web apps, include the browser and its version.

5. Show it: screenshots and screen recordings without extra apps

macOS has everything built in:

• Cmd + Shift + 4 captures a selected area. Press Space after it to capture a single window.
• Cmd + Shift + 5 opens the capture toolbar, including Record Selected Portion, which is perfect for a 10-second clip of the bug happening.
• Add Control to either screenshot shortcut (for example Cmd + Control + Shift + 4) to copy to the clipboard instead of saving a file, so you can paste straight into a GitHub issue.

GitHub accepts .mov and .mp4 uploads directly in issues, so a short recording often replaces a paragraph of description. Crop it to the part that matters.

6. Attach the logs that matter (not all of them)

Logs help when they're relevant and trimmed. A few Mac-specific places to look:

• Crash reports: open Console.app, choose Crash Reports in the sidebar, and find the entry for the app. These also live in ~/Library/Logs/DiagnosticReports/.
• Live logs: in Console.app, start streaming, filter by the process name, reproduce the bug, then stop and copy the relevant lines.
• Terminal output: rerun the failing command and capture everything, including errors:

your-command --verbose 2>&1 | tee bug-output.txt

Paste the relevant lines in a fenced code block, and attach the full file if it's long. Before you post, search the output for tokens, API keys, email addresses, and file paths that reveal more than you want. Redact them.

Need a file path for the report? In Finder, right-click the file, hold Option, and choose Copy "filename" as Pathname.

7. Say what you already tried

One short list saves a round trip:

Already tried:
- Restarted the app and the Mac
- Reinstalled v2.3.1
- Same crash with a brand-new user account
- Does NOT happen in v2.2.0

That last line is gold. "It worked in the previous version" narrows the search to one diff.

8. Make the template do the remembering

If you maintain a project, don't rely on reporters reading a guide like this. Add a GitHub issue form at .github/ISSUE_TEMPLATE/bug_report.yml:

name: Bug report
description: Something isn't working
labels: ["bug"]
body:
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      placeholder: "1. ...\n2. ...\n3. ..."
    validations:
      required: true
  - type: textarea
    id: expected-actual
    attributes:
      label: Expected vs actual behavior
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: App version and macOS version
      placeholder: "v2.3.1 on macOS 15.1 (paste output of sw_vers)"
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Logs or screenshots
      render: shell

Required fields mean you stop getting issues with no version number. If you start from the terminal, this opens the new-issue page, where the form appears:

gh issue create --web --repo owner/repo

9. Reread it as the person who has to fix it

Before you hit submit, read your report as someone who has never seen your screen. Could they reproduce it in five minutes without asking you anything? If not, the missing piece is usually a version number, an input file, or a step you did without thinking.

Keep the tone neutral. "Export crashes with an empty title" gets fixed faster than "your app is garbage," and maintainers are people who chose to give their time away.

A quick checklist

• [ ] Specific title: action, symptom, condition
• [ ] Numbered, minimal steps from a clean start
• [ ] Expected vs actual on separate lines
• [ ] sw_vers output plus the app's version
• [ ] Screenshot or short recording
• [ ] Trimmed, redacted logs
• [ ] What you already tried, and the last version that worked

One more tool, if you want it

Disclosure: I'm Rohan, and I built DraftKey, a Mac app that adds private, on-device AI autocomplete and rewriting to every Mac app, which helps when you're writing up issues, review comments, or support replies. Nothing you type leaves your Mac. It's $5 lifetime and needs macOS 14 or later on Apple Silicon: getdraftkey.com. Everything above works fine without it.