Localhost HTTPS 憑證設定教學｜mkcert 本機 SSL 完整指南

引言：讓本機也有綠色鎖頭

有些功能只能在 HTTPS 下使用：

• Service Worker（PWA 必備）
• Web Push 通知
• 地理位置 API
• WebRTC
• Clipboard API

在 localhost 使用這些功能時，雖然瀏覽器通常會放寬限制，但有時還是需要真正的 HTTPS。

本文教你用 mkcert 工具，5 分鐘設定好本機 SSL 憑證。

要點一－為什麼本機需要 HTTPS？

某些 API 需要安全連線

這些功能必須在 HTTPS 或 localhost 下才能使用：

localhost 不是都有例外嗎？

大多數情況下，瀏覽器會把 localhost 視為「安全來源」。但有些情況還是需要真正的 HTTPS：

1. 跨域請求

前端在 localhost:3000，API 在 localhost:8000，有時會遇到安全性問題。

2. 測試 Production 行為

正式環境用 HTTPS，本機也用 HTTPS 可以更準確測試。

3. Service Worker 開發

雖然 localhost 可以使用 Service Worker，但某些 PWA 功能需要完整的 HTTPS。

4. 模擬真實環境

讓開發環境盡量接近正式環境，減少上線後的意外。

要點二－自簽憑證 vs CA 憑證

什麼是自簽憑證？

自簽憑證是自己產生的憑證，沒有經過公認的 CA（憑證機構）認證。

自己產生 → 自己簽名 → 只有自己信任

問題：瀏覽器會顯示「不安全」警告。

什麼是 CA 憑證？

CA 憑證是經過憑證機構（如 Let's Encrypt、DigiCert）簽發的憑證。

你申請 → CA 驗證 → CA 簽發 → 瀏覽器信任

mkcert 的巧妙解法

mkcert 會：

1. 在你電腦建立一個本機 CA
2. 把這個 CA 加入系統的信任列表
3. 用這個 CA 簽發 localhost 憑證

結果：你的瀏覽器會信任這個憑證，不會顯示警告。

mkcert 建立本機 CA
     ↓
CA 加入系統信任
     ↓
產生 localhost 憑證
     ↓
瀏覽器顯示綠色鎖頭 ✅

要點三－mkcert 是什麼？為什麼推薦它？

mkcert 簡介

mkcert 是一個簡單的工具，用來建立本機開發用的 SSL 憑證。

GitHub：github.com/FiloSottile/mkcert

為什麼推薦 mkcert？

1. 超級簡單

mkcert localhost
# 完成！產生了 localhost.pem 和 localhost-key.pem

2. 瀏覽器不會警告

因為憑證來自已被信任的 CA，不會有紅色警告。

3. 跨平台支援

Windows、macOS、Linux 都支援。

4. 安全

只在本機使用，私鑰不會外流。

其他替代方案比較

要點四－mkcert 安裝教學

macOS 安裝

# 使用 Homebrew
brew install mkcert

# 如果要在 Firefox 也信任
brew install nss

Windows 安裝

方法一：Chocolatey

choco install mkcert

方法二：Scoop

scoop bucket add extras
scoop install mkcert

方法三：手動下載

從 GitHub Releases 下載 exe 檔案。

Linux 安裝

# Ubuntu/Debian
sudo apt install libnss3-tools
wget -O mkcert https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64
chmod +x mkcert
sudo mv mkcert /usr/local/bin/

安裝本機 CA

安裝 mkcert 後，需要安裝本機 CA 到系統：

mkcert -install

會看到：

The local CA is now installed in the system trust store! 👍

這會讓你的瀏覽器信任 mkcert 產生的憑證。

要點五－產生本機憑證

基本用法

mkcert localhost

會產生兩個檔案：

• localhost.pem：憑證
• localhost-key.pem：私鑰

加上 127.0.0.1

mkcert localhost 127.0.0.1

加上自訂網域

如果你用 hosts 檔案設定了 mysite.local：

mkcert localhost 127.0.0.1 mysite.local

加上萬用字元

mkcert "*.local" localhost 127.0.0.1

指定輸出位置

mkcert -key-file ./certs/key.pem -cert-file ./certs/cert.pem localhost

憑證檔案說明

產生的檔案：

要點六－在各框架中使用憑證

React（Create React App）

CRA 內建 HTTPS 支援：

# 設定環境變數
HTTPS=true npm start

如果要用自訂憑證：

HTTPS=true SSL_CRT_FILE=./localhost.pem SSL_KEY_FILE=./localhost-key.pem npm start

Vite

在 vite.config.js：

import { defineConfig } from 'vite'
import fs from 'fs'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('./localhost-key.pem'),
      cert: fs.readFileSync('./localhost.pem'),
    }
  }
})

Next.js

建立 server.js：

const { createServer } = require('https')
const { parse } = require('url')
const next = require('next')
const fs = require('fs')

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

const httpsOptions = {
  key: fs.readFileSync('./localhost-key.pem'),
  cert: fs.readFileSync('./localhost.pem')
}

app.prepare().then(() => {
  createServer(httpsOptions, (req, res) => {
    const parsedUrl = parse(req.url, true)
    handle(req, res, parsedUrl)
  }).listen(3000, () => {
    console.log('> Ready on https://localhost:3000')
  })
})

Express.js

const express = require('express')
const https = require('https')
const fs = require('fs')

const app = express()

const options = {
  key: fs.readFileSync('./localhost-key.pem'),
  cert: fs.readFileSync('./localhost.pem')
}

https.createServer(options, app).listen(3000, () => {
  console.log('Server running on https://localhost:3000')
})

Webpack Dev Server

在 webpack.config.js：

module.exports = {
  devServer: {
    https: {
      key: fs.readFileSync('./localhost-key.pem'),
      cert: fs.readFileSync('./localhost.pem'),
    }
  }
}

要點七－Nginx / Apache 本機 HTTPS 設定

Nginx 設定

server {
    listen 443 ssl;
    server_name localhost;

    ssl_certificate /path/to/localhost.pem;
    ssl_certificate_key /path/to/localhost-key.pem;

    location / {
        proxy_pass http://localhost:3000;
    }
}

重啟 Nginx：

sudo nginx -s reload

Apache 設定

在 httpd-vhosts.conf：

<VirtualHost *:443>
    ServerName localhost
    DocumentRoot "/var/www/html"

    SSLEngine on
    SSLCertificateFile "/path/to/localhost.pem"
    SSLCertificateKeyFile "/path/to/localhost-key.pem"
</VirtualHost>

重啟 Apache：

sudo apachectl restart

XAMPP 設定

1. 把憑證檔案放到 C:\xampp\apache\conf\ssl.crt\
2. 編輯 httpd-ssl.conf
3. 修改 SSLCertificateFile 和 SSLCertificateKeyFile 路徑

要點八－常見問題排解

問題一：瀏覽器還是顯示不安全

可能原因：
1. 沒有執行 mkcert -install
2. 憑證網域不符

解決：

# 確認 CA 已安裝
mkcert -install

# 重新產生憑證，確認網域正確
mkcert localhost 127.0.0.1

問題二：Firefox 不信任憑證

原因：Firefox 有自己的憑證庫

解決：

# macOS
brew install nss

# 重新安裝 CA
mkcert -install

問題三：ERR_SSL_KEY_USAGE_INCOMPATIBLE

原因：舊憑證格式問題

解決：重新產生憑證

mkcert -uninstall
mkcert -install
mkcert localhost

問題四：找不到憑證檔案

確認檔案路徑：

# 查看產生的檔案
ls -la *.pem

使用絕對路徑設定比較不會出錯。

問題五：port 443 被佔用

解決：

# 找出佔用的程序
# Windows
netstat -ano | findstr :443

# Mac/Linux
lsof -i :443

# 結束程序或換 port

💡 憑證設定太複雜？ 可以聯繫我們讓工程師幫你處理。

程式只能在本機跑？

讓我們幫你從 localhost 走向全世界，把專案部署到雲端。

幫我上線

常見問題 FAQ

Q1：Localhost 可以用 HTTPS 嗎？

可以。使用 mkcert 工具可以產生本機 SSL 憑證，讓 localhost 使用 HTTPS 且不會顯示瀏覽器警告。

Q2：mkcert 憑證安全嗎？

對於本機開發來說是安全的。mkcert 產生的 CA 只安裝在你的電腦，私鑰也只存在本機。不要把 mkcert 憑證用在正式環境。

Q3：為什麼不會顯示警告？

因為 mkcert 會在你的系統安裝一個本機 CA，並讓系統信任這個 CA。當你用這個 CA 簽發的憑證時，瀏覽器就會信任。

Q4：正式上線需要重新申請憑證嗎？

是的。mkcert 憑證只能用於本機開發。正式上線需要使用 Let's Encrypt 等公認 CA 簽發的憑證，或使用 Vercel、Netlify 等平台自動配置的 SSL。

延伸閱讀

• Localhost 是什麼？127.0.0.1 完整指南
• Windows Hosts 檔案設定教學｜Localhost 自訂網域名稱
• Localhost 憑證無效？5 種解決方案
• 如何讓 Localhost 上線？5 種方法總覽

程式只能在本機跑？

讓我們幫你從 localhost 走向全世界，把專案部署到雲端。

幫我上線

圖片描述

插圖 1：localhost HTTPS 概念圖
- 檔名 slug: localhost-https-concept
- 圖片類型: 概念示意圖
- 主要視覺元素:
- 左側：瀏覽器顯示綠色鎖頭和 https://localhost
- 中間：SSL 憑證圖示和 mkcert logo
- 右側：電腦圖示
- 文字標註: "https://localhost"、"mkcert"、"Secure"
- 色調與風格: 綠色調代表安全，現代簡潔風格
- 構圖建議: 水平流程圖，強調從不安全到安全的轉變

插圖 2：mkcert 安裝流程
- 檔名 slug: mkcert-install-steps
- 圖片類型: 步驟流程圖
- 主要視覺元素:
- 步驟 1：安裝 mkcert（各平台圖示）
- 步驟 2：執行 mkcert -install
- 步驟 3：成功訊息
- 文字標註: 各步驟指令和說明
- 色調與風格: 簡潔的步驟式設計
- 構圖建議: 垂直或水平的步驟序列

插圖 3：各框架 HTTPS 設定對照
- 檔名 slug: framework-https-settings
- 圖片類型: 比較表格圖
- 主要視覺元素:
- 各框架 logo（React、Vite、Next.js、Express）
- 對應設定方式簡述
- 難度標示
- 文字標註: 框架名稱、設定重點
- 色調與風格: 資訊圖表風格
- 構圖建議: 網格或表格式排列，便於比較

插圖 4：mkcert 產生的憑證檔案
- 檔名 slug: mkcert-certificate-files
- 圖片類型: 檔案結構示意
- 主要視覺元素:
- 兩個檔案圖示
- 檔案名稱標示
- 用途說明
- 文字標註: "localhost.pem（憑證）"、"localhost-key.pem（私鑰-勿外洩）"
- 色調與風格: 檔案管理器風格
- 構圖建議: 簡單的檔案列表，用顏色區分公開和私密